Welcome to Paynetics Developers Documentation hub. Happy to have you on board!
Paynetics services are built around a RESTful API. This architecture allows us to have a uniform and scalable solution for your payment services needs.
The API communication is based on JSON Encoded Requests and JSON Encoded Responses.
Paynetics also offers a sandbox environment for easy setup and testing before you are ready to go live.
BASE URL Production
BASE URL Sandbox
Paynetics API uses HMAC authentication methodology.
To authenticate your API Request to Paynetics you need to provide the following elements in the header of your request:
x-api-key : Key provided by Paynetics.
x-timestamp : Current UNIX timestamp.
x-hash : HMAC sha256. Use secret key* for hash vector. Body of the hash is formed by concatenating:
API Key + Timestamp + Operation + Content Body (Required: POST+PUT request)
Important:
{ " name ": " Paynetics " } will be {"name":"Paynetics"}
For example if request timestamp is 1591096701 and current timestamp is 1591096720 request will not be authorized!
To exchange API key and secret Paynetics require public PGP key.
Secret key
Provided by Paynetics. Keys should be kept secure to ensure your data stay safe. Never share them publicly.
Get Request
HMAC_SHA256 with API Secret of
07364675-5b2a-4d35-bd2c-b93e696aa53f1625399941cards_list
Post Request
Complete POST body which is sent HMAC_SHA256 with API Secret of 07364675-5b2a-4d35-bd2c-b93e696aa53f1625399941init_web{"openBankAccount":true,"issueCard":true}
Put Request
Complete PUT body which is sent HMAC_SHA256 with API Secret of
07364675-5b2a-4d35-bd2c-b93e696aa53f1625399941init_web{"name":"Paynetics"}
NOTE: Attach example postman authentication.
Paynetics system incorporates the API result in the following format:
HTTP Response code - is always 200 - OK. This indicates that your request has successfully reached our servers.
Detailed error codes can be found in the JSON Response body:
Example {"code": 0} = SUCCESS
* code string
All API responses come with a code attribute in the header. These indicate a variety of reasons why a request may be declined.
message string
In addition to the code, Paynetics provides a description of the error that occurred.
* mandatory
JSON GENERAL CODE SUMMARY
400 - Bad Request |
services.general.bad_request |
|---|---|
401 - Unauthorized |
services.general.http_unauthorized |
404 - Not Found |
services.general.http_not_found_exception |
500 - Exception |
services.general.http_exception |
11000 - Error |
services.general.error |
11001 - Validation Error |
services.general.validation_error |
11002 - Entity not found |
services.general.entity_not_found |
11004 - Non Unique Value |
services.general.non_unique_value |
11008 - Service request exception |
services.general.service_request_exception |
You can use Paynetics API for fetching data in bulk. Use the “list” API methodology to pull records like applications, transactions etc. Use limit and page as parameters to define the scope of your query.
Each list API can have different filters passed as query parameters.
* page string
Starting from page 1
* limit string
Maximum per page depending on the API
* mandatory
RESPONSE SUCCESS
RESPONSE VALIDATION ERROR
Request ID is a unique identifier for your API request. You can find it in the response headers, under x-request-id. Use the request ID for any escalations to our support team. This will help them quickly locate your request and resolve any issues that may have occured.
Example
X-Request-Id : 20be1835-85fb-4932-a986-a6b5fbe6b648
Welcome to Paynetics' onboarding section. We are happy to have you and your customers on board!
We provide APIs for easy integration and usage of our capabilities If your process is not ready for full API automation, we have the tools to enable your employees to use it manually:
Paynetics is a licensed EMI (Electronic Money Institution) institution, which means we need to maintain your and our partner’s trust. Paynetics is legally obliged to collect data.
There are three factors which determine what type of data we need to collect:
Paynetics will provide a list of all mandatory fields and create a configuration for your profile based on the initial agreement. Once mandatory data fields are defined, you can test our offering and decide when to move forward with live implementation.
Onboarding legal entities at Paynetics can be an automatic or semi-automatic process.
Automatic onboarding process utilizes a predefined ruleset of operations, which guide the end decision of every application.
Semi-automatic onboarding process offers assisted manual review by Paynetics' underwriting specialists. This is done after the automatic checks. This allows for a better understanding of the legal entity’s structure and background.
Note - Depending on the initial agreement Paynetics may recommend one of the two solutions above.
By submitting a request with the predefined mandatory fields. Refer to the example for the correct structure of the request. Once the request is received, Paynetics system will check the submitted fields and validate the input. Requests with invalid or missing fields will return an error prompting an update.
Once fields are validated, Paynetics system will perform a series of automatic checks, which can be:
Automation results are asynchronous and are received via webhook. Once automatic checks have concluded, Paynetics system will be configured to perform different operations depending on your initial agreement.
Paynetics system will assign and provide a unique Merchant ID (MID) and Terminal ID (TID) via webhook. Once received they are active and can be used via Paynetics API for operations and 3DS registration.
Paynetics system will provide a unique merchant identifier(token), which allows an account to be created.
Endpoint
POST /v3/applications
Operation
application_create
merchant string (32,36)
Master Merchant token
products array (1,5)
Available Options: pos , e-commerce , qr , account-opening , card-issuingdue_diligence string (0,any)
Available Options: SDD , CDDpayout_details array[object]
amount number (0,any)
Minimum amount for payout
currency string (0,any)
ISO 4217 alpha 3
iban string (0,any)
Valid IBAN to which the funds will be send
sort_code string (6,6)
Valid UK sort code
account_number string (8,8)
UK Account number
period string (0,any)
When the payout must be done
delay string (0,any)
Payout delay in days
ip_address string (0,any)
IP Address of customer submitted application
fingerprint string (0,any)
Device fingerprint of the customer submitted application
Request
code integer (0,any)
Response
Errors
11001 |
Validation error |
|---|
11008 |
Validator configuration not found |
|---|
You can add or change company details via Paynetics' API. Supported operations:
Please refer to the example for how to change company details.
Endpoint
PUT /v3/applications/{application}/companies
Operation
company_update
Parameters
[ application ]
trade_name string (0,any)
Doing business as
legal_name string (0,any)
Legal name as appears in trade reigster
website string (0,any)
URL of the website
phone string (0,any)
Phone of the company
mobile_phone string (0,any)
Mobile phone of the company
country string (2,2)
Country of the company. Format: ISO 3166-1 alpha-2
county string (0,any)
Country region of the company
city string (0,any)
City where company is registerd
zip string (0,any)
Postal/ZIP Code
address1 string (0,any)
Address of the company
address2 string (0,any)
Additional details for the address
contact_email string (0,any)
Correspondence email address
correspondence_address string (0,any)
Correspondence phisical address
description_of_activity string (0,any)
Description of the business activity of the company
address_of_shop string (0,any)
Address of the phisical shop/office of the company
business_activity string (0,any)
More details in nomernclutres section
is_sie boolean
In case the company appears in any sanctions list the field must be marked as true
Request
code integer (0,any)
Response
Errors
11001 |
Validation error |
|---|
11002 |
Application not found |
|---|
Endpoint
POST /v3/applications/{application}/companies/documents
Operation
company_add_document
Parameters
[ application ]
file string (0,any)
Base64 encoded file
file_type string (0,any)
Type of the file
Available Options: pdf , docx , xlxs , jpg , jpeg , png , mov , mp4document_type string (0,any)
More details in nomenclatures section
Available Options: idcard , bankstmt , bill , other , idcard-front , idcard-back , idcard-selfie , passport-back , passport-selfie , passport , driving-license-selfie , selfie , driving-license-front , driving-license-back , sharebook-excerpt , management-contract , moms-of-the-board , activity-license , bank-account , bulstat-registration , vat-registration , patent-law , power-of-attorney , ubo-declaration , frame-contract , sample-of-signatures , face-compare , proof , recent-excerpt , incorporation-documents , share_holders_list , other_corporate , signature , id_card_passport_photo , biometric-residence-permit-front , biometric-residence-permit-back , kyc-vendor-reportRequest
code integer (0,any)
Response
Errors
11001 |
Validation error |
|---|
11002 |
Application not found |
|---|
Endpoint
POST /v3/applications/{application}/companies/members
Operation
company_add_member
Parameters
[ application ]
first_name string (0,any)
First name of the member
last_name string (0,any)
Last name of the member
mobile_phone string (0,any)
Mobile phone of the member
phone string (0,any)
Phone of the member
legal_name string (0,any)
Used when member is other legal entity
uic string (0,any)
Business registration number.Used when member is other legal entity
country string (0,any)
Country of birth or country of legal entity.ISO 3166-1 alpha-2
country_of_residence string (0,any)
ISO 3166-1 alpha-2
zip string (0,any)
Postal/Zip code of the member.
city string (0,any)
City of the member.
address1 string (0,any)
Address of the member.
address2 string (0,any)
Additional info for the address
county string (0,any)
Region of the member
ownership boolean
Only for UBO to specify the percentage of the ownership
ownership_percentage integer (0,any)
Only for UBO to specify the percentage of the ownership
type array (1,2)
Available Options: ubo , ceo , representative , proxy , legal-entity , officerunique_identifier string (0,any)
Unique number of persons on offical document.
user string (0,any)
Existing user in Paynetics system to get KYC details
legal_form string (0,any)
Legal form of the company
Available Options: sole-trader , limited-company , limited-partnership , limited-liability-partnership , other , self-employedplace_of_birth string (0,any)
ISO 3166-1 alpha-2
pep_declaration boolean
Mark as PEP
pep_related_declaration boolean
Mark as PEP relative
is_sip boolean
Mark as that appears in sanction lists
birthday string (0,any)
Date of birth
nationality string (0,any)
ISO 3166-1 alpha-2
contact_email string (0,any)
documents array[object]
file string (0,any)
Base64 encoded file
file_type string (0,any)
Type of the file
Available Options: pdf , docx , xlxs , jpg , jpeg , png , mov , mp4document_type string (0,any)
More details in nomenclatures section
Available Options: idcard , bankstmt , bill , other , idcard-front , idcard-back , idcard-selfie , passport-back , passport-selfie , passport , driving-license-selfie , selfie , driving-license-front , driving-license-back , sharebook-excerpt , management-contract , moms-of-the-board , activity-license , bank-account , bulstat-registration , vat-registration , patent-law , power-of-attorney , ubo-declaration , frame-contract , sample-of-signatures , face-compare , proof , recent-excerpt , incorporation-documents , share_holders_list , other_corporate , signature , id_card_passport_photo , biometric-residence-permit-front , biometric-residence-permit-back , kyc-vendor-reportRequest
code integer (0,any)
Response
Errors
11001 |
Validation error |
|---|
11002 |
Application not found |
|---|
Endpoint
PUT /v3/applications/{application}/companies/members/{token}
Operation
company_member_update
Parameters
[ application ]
[ token ]
first_name string (0,any)
First name of the member
last_name string (0,any)
Last name of the member
mobile_phone string (0,any)
Mobile phone of the member
phone string (0,any)
Phone of the member
legal_name string (0,any)
Used when member is other legal entity
country string (0,any)
Country of birth or country of legal entity.ISO 3166-1 alpha-2
country_of_residence string (0,any)
ISO 3166-1 alpha-2
zip string (0,any)
Postal/Zip code of the member.
city string (0,any)
City of the member.
address1 string (0,any)
Address of the member.
address2 string (0,any)
Additional info for the address
county string (0,any)
Region of the member
ownership boolean
Only for UBO to specify the percentage of the ownership
ownership_percentage integer (0,any)
Only for UBO to specify the percentage of the ownership
legal_form string (0,any)
Legal form of the company
Available Options: sole-trader , limited-company , limited-partnership , limited-liability-partnership , other , self-employedpep_declaration boolean
Mark as PEP
pep_related_declaration boolean
Mark as PEP relative
is_sip boolean
Mark as that appears in sanction lists
contact_email string (0,any)
status string (0,any)
Available Options: active , inactiveRequest
code integer (0,any)
Response
Errors
11001 |
Validation error |
|---|
11002 |
Company member not found |
|---|
Endpoint
POST /v1/kyc
Operation
kyc_init
user string (0,any)
Token of the user
Request
code integer (0,any)
Response
Errors
11002 |
payoo.users.not_found |
|---|
Endpoint
POST /v3/applications/{application}/companies/members/{token}/documents
Operation
company_member_add_document
Parameters
[ application ]
[ token ]
file string (0,any)
Base64 encoded file
file_type string (0,any)
Type of the file
Available Options: pdf , docx , xlxs , jpg , jpeg , png , mov , mp4document_type string (0,any)
More details in nomenclatures section
Available Options: idcard , bankstmt , bill , other , idcard-front , idcard-back , idcard-selfie , passport-back , passport-selfie , passport , driving-license-selfie , selfie , driving-license-front , driving-license-back , sharebook-excerpt , management-contract , moms-of-the-board , activity-license , bank-account , bulstat-registration , vat-registration , patent-law , power-of-attorney , ubo-declaration , frame-contract , sample-of-signatures , face-compare , proof , recent-excerpt , incorporation-documents , share_holders_list , other_corporate , signature , id_card_passport_photo , biometric-residence-permit-front , biometric-residence-permit-back , kyc-vendor-reportRequest
code integer (0,any)
Response
Errors
11001 |
Validation error |
|---|
11002 |
Company member not found |
|---|
Endpoint
POST /v2/users
Operation
user_create
email string (0,any)
Email address of the user
first_name string (0,any)
First name of the user
last_name string (0,any)
Last name of the user
address1 string (0,any)
Address of the user
address2 string (0,any)
country string (0,any)
Country of resident of the user (Alpha-2)
city string (0,any)
City of the user
zip string (0,any)
ZIP/Postal Code of the user
phone string (0,any)
Phone of the user
mobile_phone string (0,any)
Mobile Phone of the user
language string (0,any)
nationality string (0,any)
Nationality of the user (Alpha-2)
birthday string (0,any)
Date of birth of the user (YYYY-MM-DD)
aml string (0,any)
place_of_birth string (0,any)
merchant string (32,36)
Master Merchant token
occupation string (0,any)
education string (0,any)
info string (0,any)
money_declaration string (0,any)
source_of_funds string (0,any)
external_reference string (0,any)
registration_ip string (0,any)
is_san string (0,any)
is_sip string (0,any)
peps_declaration string (0,any)
pep string (0,any)
pep_relative string (0,any)
unique_identifier string (0,any)
id_passport_validity string (0,any)
id_passport_number string (0,any)
type string (0,any)
Available Options: card-usage , defaultdocuments array[object]
file string (0,any)
Base64 encoded file
file_type string (0,any)
Type of the file
Available Options: pdf , docx , xlxs , jpg , jpeg , png , mov , mp4document_type string (0,any)
More details in nomenclatures section
Available Options: idcard , bankstmt , bill , other , idcard-front , idcard-back , idcard-selfie , passport-back , passport-selfie , passport , driving-license-selfie , selfie , driving-license-front , driving-license-back , sharebook-excerpt , management-contract , moms-of-the-board , activity-license , bank-account , bulstat-registration , vat-registration , patent-law , power-of-attorney , ubo-declaration , frame-contract , sample-of-signatures , face-compare , proof , recent-excerpt , incorporation-documents , share_holders_list , other_corporate , signature , id_card_passport_photo , biometric-residence-permit-front , biometric-residence-permit-back , kyc-vendor-reportcompany string (0,any)
Request
Endpoint
PUT /v2/users/{user}
Operation
user_update
Parameters
[ user ]
Token from user creation
first_name string (0,any)
First name of the user
last_name string (0,any)
Last name of the user
address1 string (0,any)
Address of the user
address2 string (0,any)
country string (0,any)
Country of resident of the user (Alpha-2)
city string (0,any)
City of the user
zip string (0,any)
ZIP/Postal Code of the user
phone string (0,any)
Phone of the user
mobile_phone string (0,any)
Mobile Phone of the user
language string (0,any)
nationality string (0,any)
Nationality of the user (Alpha-2)
birthday string (0,any)
Date of birth of the user (YYYY-MM-DD)
place_of_birth string (0,any)
merchant string (32,36)
Master Merchant token
occupation string (0,any)
education string (0,any)
info string (0,any)
money_declaration string (0,any)
source_of_funds string (0,any)
external_reference string (0,any)
is_san string (0,any)
is_sip string (0,any)
peps_declaration string (0,any)
pep string (0,any)
pep_relative string (0,any)
unique_identifier string (0,any)
id_passport_validity string (0,any)
id_passport_number string (0,any)
Request
code integer (0,any)
Response
Endpoint
GET /v2/users/{user}
Operation
user_details
Parameters
[ user ]
Token from user creation
email string (0,any)
Email address of the user
first_name string (0,any)
First name of the user
last_name string (0,any)
Last name of the user
address1 string (0,any)
Address of the user
address2 string (0,any)
country string (0,any)
Country of resident of the user (Alpha-2)
city string (0,any)
City of the user
zip string (0,any)
ZIP/Postal Code of the user
phone string (0,any)
Phone of the user
mobile_phone string (0,any)
Mobile Phone of the user
language string (0,any)
nationality string (0,any)
Nationality of the user (Alpha-2)
birthday string (0,any)
Date of birth of the user (YYYY-MM-DD)
aml string (0,any)
place_of_birth string (0,any)
merchant string (32,36)
Master Merchant token
occupation string (0,any)
education string (0,any)
info string (0,any)
money_declaration string (0,any)
source_of_funds string (0,any)
external_reference string (0,any)
registration_ip string (0,any)
is_san string (0,any)
is_sip string (0,any)
peps_declaration string (0,any)
pep string (0,any)
pep_relative string (0,any)
unique_identifier string (0,any)
id_passport_validity string (0,any)
id_passport_number string (0,any)
type string (0,any)
Available Options: card-usage , defaultResponse
Endpoint
DELETE /v2/users/{user}
Operation
user_remove
Parameters
[ user ]
Token from user creation
code integer (0,any)
Response
Endpoint
POST /v2/users/{user}/documents
Operation
user_add_document
Parameters
[ user ]
file string (0,any)
Base64 encoded file
file_type string (0,any)
Type of the file
Available Options: pdf , docx , xlxs , jpg , jpeg , png , mov , mp4document_type string (0,any)
More details in nomenclatures section
Available Options: idcard , bankstmt , bill , other , idcard-front , idcard-back , idcard-selfie , passport-back , passport-selfie , passport , driving-license-selfie , selfie , driving-license-front , driving-license-back , sharebook-excerpt , management-contract , moms-of-the-board , activity-license , bank-account , bulstat-registration , vat-registration , patent-law , power-of-attorney , ubo-declaration , frame-contract , sample-of-signatures , face-compare , proof , recent-excerpt , incorporation-documents , share_holders_list , other_corporate , signature , id_card_passport_photo , biometric-residence-permit-front , biometric-residence-permit-back , kyc-vendor-reportRequest
code integer (0,any)
Response
Errors
11001 |
Validation error |
|---|
11002 |
Application not found |
|---|
You can check AML and sanctions presence:
Endpoint
POST /v1/aml
Operation
aml_check
first_name string (0,any)
last_name string (0,any)
nationality string (0,any)
birthday string (0,any)
Request
code integer (0,any)
Response
Errors
18000 |
services.general.invalid_processor |
|---|
18001 |
service.aml.match.found |
|---|
Welcome to Paynetics' transactions section. Let’s go over the basics.
Transaction in paynetics system is a record that represents an operation that affect the ballance of the end customer. This can be a blockage or a movement of funds internally in the system or externally to other banks.
Examples for Internal movements:
Examples for External movements:
| Code | Mapping | Impacts Balance |
|---|---|---|
| internal-transfer | Financial | Yes |
| load | Financial | Yes |
| wire-transfer | Financial | Yes |
| authorization | Authorization | Yes |
| refund | Authorisation | Yes |
| reversal | Authorisation | Yes |
| fee | Financial | Yes |
| oct | Financial | Yes |
| presentment | Financial | Yes |
Depending on the type, the transaction may have a different structure.
counterpart is a mandatory field for all internal transfers. It contains the details of debtor/creditor.wires is a mandatory field for cases of internal transfers done using IBANEndpoint
GET /v2/transactions/{page}/{limit}
Operation
transactions_list
Parameters
[ page ]
Starting from page 1
[ limit ]
Maximum per page 1000
Filters
start_date - (For this date onwards)
end_date - (Up to this date)
type - (Type of the transaction. For more info check)
code - (Code of the transaction. For more info check)
channel - ()
status - (Status of the transaction. For more info)
merchant - (Identifier of merchant|company in Paynetics system)
user - (Identifier of user in Paynetics system)
reference - (Reference of the transaction)
show_hidden - (Force show hidden transactions)
account - (Identifier of the account in Paynetics system)
balance - (Identifier of the balance in Paynetics system)
card - (Identifier of the card in Paynetics system)
debit_credit - (Direction of transction debit or credit)
load_after - (Load transaction from specified identifier onwards)
code integer (0,any)
Response
Endpoint
GET /v2/transactions/{transaction}
Operation
transaction_details
Parameters
[ transaction ]
code integer (0,any)
Response
Your initial agreement with Payntics includes a definition of how you intend to use Paynetics' services. This includes types of products, limits etc. Program is configured by Paynetics and is used as a term that refers to a set of rules used for account and card creation as well as management.
The program configuration allows for a wide range of settings:
Balances settings
All accounts have one primary (main) balance that can be set in one of Paynetics' supported currencies.
Paynetics supports multiple secondary balances that can be set in the preferred supported currency.
Based on the settings, accounts can have one IBAN linked to the primary (main) balance or multiple IBANs for each secondary balance.
KYC requirements
Each program comes with configurable KYC onboarding requirements settings. Some programs may require KYC verification for natural persons. This is set up depending on the initial agreement.
Card settings
Paynetics offers plastic and virtual card issuing, which can be enabled via the available configurations in the program.
Cards can be configured to have enabled/disabled card push provisioning for Apple pay and Google pay wallets.
The program specifies the processor and the default limit and fee groups for it. Other configurations include direct issuing and the max lenght of the name on cards.
Accounts are entities created against a merchant or user with the respective program. They can have one or multiple balances depending on your program.
Accounts at Paynetics can perform a large number of operations.
IBAN - Accounts can have one or multiple IBANs depending on the program.
Supported currencies: EUR, BGN, GBP (Account number + Sort Code)
Virtual Accounts - Virtual accounts are linked to one main account and do not hold a balance. Instead, they are using the primary (main) account balance.
Card - A single card can be issued to an account. Cards can be plastic and/or virtual.
Money transfers - Account holders can send and receive money internally to/from another Paynetics account or externally to/from any IBAN.
Spend money by card - Cards can be used to pay in any physical location, online or withdraw money from ATMs.
Load - There are multiple ways accounts can be loaded:
There are several types of accounts that can be created:
Default
Funding
Virtual
Breakage
Accounts are created via an API request. Each request should include the program and the merchant/user associated with it.
For cases where IBAN/Account Number creation is allowed by the program, but should be omitted for a specific account, a property in the API request can be used to skip that step.
For cases where a virtual account must be created, please include the primary (main) account identifier in the API request. It is mandatory that the primary (main) account is opened to the same merchant/user as in the request.
If the request is successful, the API response will return an account identifier and an array of balances with identifiers to each one. It is recommended these identifiers are stored by external parties for later usage.
For merchant virtual accounts, Paynetics system checks if the primary (main) account exists and has valid KYB verification.
For user virtual accounts, Paynetics system checks if the primary (main) account is not blocked/terminated and has valid KYC verification.
Each merchant/user can have multiple primary (main) and virtual accounts.
Endpoint
POST /v2/accounts
Operation
account_create
program string (0,any)
merchant string (0,any)
user string (0,any)
main string (0,any)
skip_iban_generation boolean
alias string (0,any)
Request
code integer (0,any)
Response
There are 3 statuses that an account can have:
Active
By default, accounts are created in active status. This means that the account can be loaded using an external bank card, wire transfer, or internal transfer. Wire/internal transfers can also be initiated by the account owner.
Active accounts can have plastic and/or virtual cards that can be used to spend available funds.
Inactive
Inactive status restricts the account holder to spend or receive any funds. Cards cannot be issued. This status is reversible to active. If any cards are issued to the account, they are frozen as well as any Apple/Google tokens
Closed
Closed have same properties as inactive but it also destroys all cards issued, remove all apple/google tokens. Account closure is an irreversible operation.
There are two different APIs for account status change. One is for changing between active/inactive status and a separate one is used for account termination since it is an irreversible process.
Endpoint
PUT /v2/accounts/{account}/status
Operation
account_status
Parameters
[ account ]
Token from account creation
status string (0,any)
Available Options: active , blockedRequest
code integer (0,any)
Response
Endpoint
DELETE /v2/accounts/{account}
Operation
account_terminate
Parameters
[ account ]
Token from account creation
code integer (0,any)
Response
Account list/details can be extracted using API.
List API is used to extract basic information for all accounts associated with an instance. There are several filters that can be used to refine your query.
Endpoint
GET /v2/accounts/{page}/{limit}
Operation
accounts_list
Parameters
[ page ]
Starting from page 1
[ limit ]
Maximum per page 10
Filters
merchant - (Token of merchant)
user - (Token of user)
program - (Code of program)
code integer (0,any)
Response
Details API is used to return full information for the account and associated balances.
Endpoint
GET /v2/accounts/{account}
Operation
account_details
Parameters
[ account ]
Token from account creation
code integer (0,any)
Response
Cards can be issued to an account or can be non-personalized depending on program configuration. Each account can have a single active card. Card can be either virtual or plastic depending on the program. Cards can be used to pay in any physical location, online or withdraw money from ATMs. All virtual cards are activated upon issuing and can be used immediately. All plastic cards are not activated upon issuing and must be activated by the customer once received.
All virtual cards are activated upon issuing and can be used immediately.
All plastic cards are not activated upon issuing and must be activated by the customer once received.
Cards can be converted from virtual to plastic at a later stage. The PIN can be set on card creation or changed at a later stage on ATM.
Apple Pay/Google Pay push provision is supported depending on the program.
Card creation can require different fields depending on type (virtual, plastic) and affiliation (customer, non-personalized).
Virtual Cards - to create a virtual card associated with a customer account, please include the account identifier and type of card (virtual). In case the name of the merchant/user is not present in the customer profile, please specify them in the emboss name, emboss name line 4, first and last name (for natural persons) fields of the API request.
Plastic Cards - the requirements for plastic card issuing for an account associated with a customer are similar to those for virtual cards. The only addition is to include the delivery details of the cardholder.
The program associated with the account will be used when the card is created. Virtual accounts use the balance of the primary (main) account.
Non-personalized virtual cards - the required fields are program code and type of the card (virtual).
Non-personalized plastic cards - the requirements for non-personalized plastic card issuing are similar to those for non-personalized virtual cards. The only addition is to include the card delivery details.
For all cases above there are additional fields which can be provided like PIN, fulfil and thermal line data. Card 3DS details can also be provided in order for the card to be enrolled immediately after creation.
Please be advised that fulfil and thermal line data usage and placement on the card may vary depending on the personalization bureau. Contact your account manager before usage.
Endpoint
POST /v2/cards
Operation
card_create
program string (0,any)
account string (0,any)
merchant string (0,any)
Required only for non pesonalized card in case must be assigned to merchant immediately.
user string (0,any)
Required only for non pesonalized card in case must be assigned to user immediately.
aml string (0,any)
Token of AML check. Conditinal: depending on program configuration
emboss_name string (0,any)
emboss_name_line4 string (0,any)
fulfil1 string (0,any)
fulfil2 string (0,any)
thermal_line1 string (0,any)
thermal_line2 string (0,any)
active boolean
pin string (0,any)
type string (0,any)
Available Options: plastic , virtualfirst_name string (0,any)
last_name string (0,any)
alias string (0,any)
url string (0,any)
Request
code integer (0,any)
Response
Endpoint
PUT /v2/cards/{card}
Operation
card_update
Parameters
[ card ]
merchant string (0,any)
Required only for non pesonalized card in case must be assigned to merchant immediately.
user string (0,any)
Required only for non pesonalized card in case must be assigned to user immediately.
emboss_name string (0,any)
mobile_phone string (0,any)
first_name string (0,any)
last_name string (0,any)
branch_code string (0,any)
expiration_month string (0,any)
expiration_year string (0,any)
Request
code integer (0,any)
Response
Virtual cards can be converted to plastic. The requirement for conversion is card delivery details to be present when the virtual card was created or added when making a request to the conversion API endpoint.
Endpoint
PUT /v2/cards/{card}/convert
Operation
card_convert
Parameters
[ card ]
Token from card creation
code integer (0,any)
Response
Plastic cards are always created not activated, meaning no transactions can be executed with the card before activation. Activation is a one-time process and must be done once the card is received by the cardholder for security reasons.
Endpoint
PUT /v2/cards/{card}/activate
Operation
card_activate
Parameters
[ card ]
Token from card creation
aml string (0,any)
Conditional: For some cases for non personalized cards.
Request
code integer (0,any)
Response
There are 3 statuses that a card can have:
Active
By default, cards are created in active status. This means that card transactions can be executed with the card on POS, ATM, E-commerce, etc.
Please be advised, active status is different than card activation. While activation is a one-time process, card statuses can be changed between active/inactive at any time.
Inactive
Inactive status restricts all transactions with the card. The status is reversable to active.
Closed
Void status destroys the card. No transactions can be done.
The status is not reversable!
Endpoint
PUT /v2/cards/{card}/status
Operation
card_status
Parameters
[ card ]
Token from card creation
status string (0,any)
Available Options: active , inactiveRequest
code integer (0,any)
Response
Endpoint
DELETE /v2/cards/{card}
Operation
card_terminate
Parameters
[ card ]
Token from card creation
code integer (0,any)
Response
Endpoint
PUT /v2/cards/{card}/renew
Operation
card_renew
Parameters
[ card ]
mode integer (0,any)
Request
code integer (0,any)
Response
By default, limit and fee groups are set upon card creation depending on program configuration. Each limit/fee group can be changed or removed at any time.
The group codes will be provided by Paynetics and must be associated with the program, or the change will not be executed.
Endpoint
GET /v2/cards/{card}/groups
Operation
card_groups
Parameters
[ card ]
Token from card creation
code integer (0,any)
Response
Endpoint
PUT /v2/cards/{card}/groups
Operation
card_groups
Parameters
[ card ]
Token from card creation
usage string (0,any)
fees string (0,any)
schedule_fees string (0,any)
web_service_fees string (0,any)
limits string (0,any)
linkage string (0,any)
mcc string (0,any)
whitelist string (0,any)
Request
code integer (0,any)
Response
Endpoint
GET /v2/cards/{page}/{limit}
Operation
cards_list
Parameters
[ page ]
[ limit ]
Filters
merchant - (Token of merchant)
user - (Token of user)
code integer (0,any)
Response
Endpoint
GET /v2/cards/{card}
Operation
card_details
Parameters
[ card ]
Token from card creation
[ card ]
Token from card creation
code integer (0,any)
Response
Endpoint
GET /v2/cards/{card}/first-half
Operation
card_number
Parameters
[ card ]
Token from card creation
code integer (0,any)
Response
Endpoint
GET /v2/cards/{card}/second-half
Operation
card_number
Parameters
[ card ]
Token from card creation
code integer (0,any)
Response
Card PIN can be retrieved using API at any time.
Endpoint
GET /v2/cards/{card}/pin
Operation
card_retrieve_pin
Parameters
[ card ]
Token from card creation
code integer (0,any)
Response
It can be sent to the cardholder via SMS depending on the program configuration. The mobile phone number added upon card creation will be used. In case the phone number must be changed please use the cardholder details update API.
Endpoint
POST /v2/cards/{card}/pin/send
Operation
card_send_pin
Parameters
[ card ]
Token from card creation
code integer (0,any)
Response
Error counter can be reset using API. This is needed in case the cardholder has entered an incorrect PIN/CVV several times on POS, ATM or online.
Endpoint
DELETE /v2/cards/{card}/pin/reset
Operation
card_reset_pin
Parameters
[ card ]
Token from card creation
code integer (0,any)
Response
Card can be enrolled for 3DS for both OTP SMS authentication and/or biometric authentication. For OTP SMS authentication the mobile phone number of the account holder is required.
Endpoint
POST /v2/cards/{card}/3ds
Operation
card_3ds_enrol
Parameters
[ card ]
Token from card creation
otp_sms string (0,any)
biometric boolean
Request
code integer (0,any)
Response
* number can be amended at a later stage.
Endpoint
PUT /v2/cards/{card}/3ds
Operation
card_3ds_update
Parameters
[ card ]
Token from card creation
otp_sms string (0,any)
Request
code integer (0,any)
Response
* can be disabled at any time but is not recommended.
Endpoint
DELETE /v2/cards/{card}/3ds
Operation
card_3ds_remove
Parameters
[ card ]
Token from card creation
type string (0,any)
Request
code integer (0,any)
Response
Endpoint
POST /v2/cards/{card}/3ds/process
Operation
card_3ds_process
Parameters
[ card ]
request string (0,any)
status string (0,any)
Available Options: SUCCESS , FAILURERequest
code integer (0,any)
Response
Apple/Google wallet push provisioning is supported depending on the program. Push provisioning is used for automatic In-App provisioning for both platforms.
API request will return an encrypted payload required for the card to be added to Apple/Google wallet using platform SDK/API.
Endpoint
POST /v2/cards/{card}/apple/encrypt
Operation
enc_card
Parameters
[ card ]
Token from card creation
code integer (0,any)
Response
Endpoint
POST /v2/cards/{card}/google/encrypt
Operation
enc_card
Parameters
[ card ]
Token from card creation
code integer (0,any)
Response
Endpoint
GET /v2/cards/{card}/tokens/{deviceId}
Operation
card_tokens
Parameters
[ card ]
Token from card creation
[ deviceId ]
Device ID
code integer (0,any)
Response
To move funds between accounts within the system or to external banks customers must have an account/card opened in advance. Transfers API may have different requirements depending on the type of transfer (internal/wire). Amount, currency, debtor, and creditor are required for all requests.
Debtor is the customer from which the funds will be deducted.
Creditor is the customer/external account that will receive the funds.
Internal transfers can be initiated between accounts/cards in the system using several identifiers like balance identifier, IBAN, Sort Code and Account Number.
As a response from the API call, a transaction identifier will be received when transfer is successful. The transfer is a real-time operation, meaning that in case a transaction identifier is received the transfer has been completed.
For wire transfer account must have IBAN or account number generated for a specific payment network. The network is routed depending on the currency and/or program configurations.
For most wire transfers there are additional requirements for creditor name, address, and country (depending on the network).
Debtor name, address, and country will also be required in case they are missing in the customer profile.
A response from the API call, a transaction identifier will be received when the transfer is successfully initiated. Wire transfers are not processed in real-time the way internal transfers are. There might be a delay between several seconds to several days depending on the payment network. When the transfer has been processed a webhook (link to webhook) with the status of the transfer will be sent.
Endpoint
POST /v2/transfers
Operation
transfer
amount number (0,any)
Amount to be deducted from customer account
currency string (0,any)
Available Options: EUR , BGN , GBPcode string (0,any)
link string (0,any)
Link to another transaction
reference string (0,any)
reference2 string (0,any)
reference3 string (0,any)
reference4 string (0,any)
origin_of_funds string (0,any)
Available Options:description string (0,any)
is_instant boolean
Only for SEPA transfers (EUR)
cop string (0,any)
Confirmatino of Payee token
Request
code integer (0,any)
Response
Errors
11000 |
services.general.error |
|---|
11001 |
services.general.validation_error |
|---|
16013 |
services.balances.balance_not_updated |
|---|
16014 |
services.balances.insufficient_funds |
|---|
16015 |
services.balances.debtor_balance_not_found |
|---|
16016 |
services.balances.creditor_balance_not_found |
|---|
16017 |
services.balances.conversion_rate_not_available |
|---|
16018 |
services.balances.blocked_amount |
|---|
16019 |
services.balances.transfer_to_same_balance |
|---|
16020 |
services.balances.transfer_to_same_main_account |
|---|
20001 |
services.balances.sepa_instant_not_supported_by_creditor_bank |
|---|
Endpoint
POST /v2/cop
Operation
cop
account_number string (0,any)
sort_code string (0,any)
account_type string (0,any)
account_name string (0,any)
secondary_reference string (0,any)
user string (0,any)
merchant string (0,any)
Request
code integer (0,any)
Response
Response Codes
| Reason code | Code description | True/False | Long description | Account name passed back |
|---|---|---|---|---|
| N/A | N/A | TRUE | The CoP Responder has performed the matching and confirms it is a match | No |
| ANNM | Account name does not match | FALSE | The CoP Responder has performed the matching and confirms it is not a match | No |
| MBAM | There may be a match on the account name | FALSE | The CoP Responder has performed the matching and it is a close match | Yes |
| BANM | Business account, name matches | FALSE | The CoP Requester indicated that the Payer intends to pay a personal account, but the actual account is a business account and the name matches. | No |
| PANM | Personal account, name matches | FALSE | The CoP Requester indicated that the Payer intends to pay a business account, but the actual account is a personal account and the name matches | No |
| BAMM | Business account, name may be a match | FALSE | The CoP Requester indicated that the Payer intends to pay a personal account, but the actual account is a business account and the name is a close match | Yes |
| PAMM | Personal account, name may be a match | FALSE | The CoP Requester indicated that the Payer intends to pay a business account, but the actual account is a personal account and the name is a close match | Yes |
| AC01 | Incorrect account number | FALSE | Account does not exist in the CoP Responder’s books | No |
| IVCR | Invalid Customer Reference | FALSE | The CoP Responder was unable to locate the customer account based on the secondary reference data contained within the Secondary Identification field | No |
| ACNS | Account type Not Supported for CoP | FALSE | Account not supported for CoP by the CoP Responder. This code should also be used by a sponsor bank if the account relates to a collection account held by an ASPSP that is not reachable for CoP and they instruct payers to enter the SRD account level name for inbound payments as the sponsor will not be able to match based on the collection account name | No |
| OPTO | Opted out of CoP Scheme | FALSE | Payee has been opted out of the CoP service by the CoP Responder | No |
| CASS | Account has been switched | FALSE | The Payee’s account has been switched using the Current Account Switch Service (CASS) | No |
| SCNS | Sort code not supported at endpoint | FALSE | The CoP Responder has incorrectly received a CoP request for a sort code that does not belong to them | No |
Based on instance level configuration the IWT will be placed in queue where external system can make decision what must have done with the transfer.
System will automatically return the transfer in case the account is not found, closed, or blocked.
Once the transfer has been added into the queue webhook will be sent to external system with token (identifier) of the queue record.
In case the webhook has not been received from the first time the system will try to resend it 3 more times.
Example of the webhook can be found webhooks section TRANSACTION.SUSPENDED
Endpoint
GET /v2/queue/{page}/{limit}
Operation
queue_list
Parameters
[ page ]
Starting from page 1
[ limit ]
Maximum per page 1000
Filters
merchant - (Identifier of merchant in Paynetics system)
code integer (0,any)
Response
Endpoint
GET /v2/queue/{token}
Operation
queue_details
Parameters
[ token ]
Token of the queue entry
code integer (0,any)
Response
Endpoint
POST /v2/queue/{token}/process
Operation
queue_process
Parameters
[ token ]
Token of the queue entry
code integer (0,any)
Response
Endpoint
DELETE /v2/queue/{token}/return
Operation
queue_return
Parameters
[ token ]
Token of the queue entry
return_reason string (0,any)
Available Options: incorrect-account-number , closed-account-number , blocked-account , beneficiary-deceased , account-cannot-be-identified , beneficiary-account-name-does-not-match-beneficiary-account-number , return-requested-by-sender-of-original-payment , account-is-not-in-currency-quoted , beneficiary-not-expecting-funds-or-instructed-return , terms-and-conditions-of-account-do-not-permit-crediting-of-funds , sending-fps-institution-action-required , account-transferred , payment-cannot-be-applied-because-of-beneficiary-sensitivities , other , transaction-forbidden , invalid-bank-operation-code , duplication , missing-creditor-address , creditor-bank-is-not-registered , eri-option-not-supported , end-customer-deceased , not-specified-reason-customer-generated , not-specified-reason-agent-generated , bank-identifier-incorrect , missing-debtor-account-or-identification , missing-debtor-name-or-address , missing-creditor-name-or-address , regulatory-reason , following-cancellation-requestRequest
code integer (0,any)
Response
Endpoint
POST /v2/batch
Operation
batch_create
Request
code integer (0,any)
Response
In a Card SDK, OTP (One-Time Password) verification is used to securely display card data. When users request access to sensitive information, an OTP should be generated between hosts and sent to SDK verify their value. After providing the correct OTP, the SDK grants access to view the card details, adding an extra layer of security.
Endpoint
POST /v2/sdk/otp
Operation
sdk_otp
card string (0,any)
device_id string (0,any)
Request
code integer (0,any)
Response
Merchant created
Merchant risk score
Account iban
Transaction new
Transaction update
Balance update
Transaction Suspended
To understand better how our API works and speed up your integration process, you can download our Postman collection.
In order to use it, the following will be provided to you by your account/project manager:
1.API Key + Secret.
2.Requirements for onboarding of legal entities or natural persons.
3.Program code needed for account/card creation.
4.Others - depending on your business case.
You can download and install Postman on all operating systems from https://www.postman.com/downloads/
Click here
First things first. You need to import the collection into your Postman App.
In top left corner there is import button which will open modal where you can add the file downloaded in
step 2.
After successfully importing the collection you need to make simple configuration.
Click on the collection variable section where you will find API_KEY and API_SECRET variables.
Please enter the credentials provided to you by your account/project manager.
BE AWARE THAT BOTH INITIAL AND CURRENT VALUE FIELDS
MUST BE FILED
You can now start using the collection and explore the API.
Just few additional tips and todos.
Each body of each request is located in Pre Request section.
The pre request script execute a function which will calculate the authentication value and add need
headers for authentication.
The operation and body of the request (if any) are passed as arguments to the function which
authenticates the request.
You can use this function for additional request in order to authenticate.
There will some parts of the json body which must be added by you.
You will find the as {{ todo sections }} with explanation what must be done.
