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
Authentication
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-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:
Body content whitespaces will be omitted when comparing hashes!
{ " name ": " Paynetics " }will be{"name":"Paynetics"}
Request is valid for 15 seconds after hash generation!
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.
Hash Generation Examples:
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.
Errors
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
Attributes
*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
Pagination
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.
Attributes
*page string
Starting from page 1
*limit string
Maximum per page depending on the API
* mandatory
RESPONSE SUCCESS
RESPONSE VALIDATION ERROR
Request IDs
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.
Welcome to Paynetics' onboarding section. We are happy to have you and your
customers on board!
Through Paynetics, you can:
Open accounts
Make transfers
Issue cards and control them
Use our acquiring services
Onboard merchants
Use our white-label wallet solution for added value and convenience
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:
our onboarding portal
our card management portal
Collecting Data
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:
What type of clients do you intend to onboard (Individuals/Legal Entities)?
Which of our products do you wish to access?
What is your current onboarding process?
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.
Legal Entities Onboarding
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.
Submitting Application
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.
Automatic Checks
Once fields are validated, Paynetics system will perform a series of automatic checks, which can be:
Risk Calculation - Paynetics calculates the risk profile of each new application based on provided data.
Automatic Verification - Paynetics uses a third-party provider to extract information from local trade
registration bureaus to verify company details.
Security Checks - Paynetics uses a third-party provider to screen every new entity for adverse media and
sanction lists presence.
Results
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.
Acquiring
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.
Account Opening and Issuing
Paynetics system will provide a unique merchant identifier(token), which allows an account to be created.
Endpoint
POST
/v3/applications
Operation
application_create
Request
Structure
merchantstring(32,36)
Master Merchant token
productsarray(1,5)*
Available Options: pos , e-commerce , qr , account-opening , card-issuing
due_diligencestring(0,any)
Available Options: SDD , CDD
companyobject
Company Details
trade_namestring(0,any)
Doing business as
legal_namestring(0,any)
Legal name as appears in trade reigster
uicstring(0,any)
Business Registration Number
incorporation_datestring(0,any)
Date of the company incorporation
websitestring(0,any)
URL of the website
phonestring(0,any)
Phone of the company
mobile_phonestring(0,any)
Mobile phone of the company
countrystring(2,2)
Country of the company. Format: ISO 3166-1 alpha-2
countystring(0,any)
Country region of the company
citystring(0,any)
City where company is registerd
zipstring(0,any)
Postal/ZIP Code
address1string(0,any)
Address of the company
address2string(0,any)
Additional details for the address
contact_emailstring(0,any)
Correspondence email address
correspondence_addressstring(0,any)
Correspondence phisical address
description_of_activitystring(0,any)
Description of the business activity of the company
address_of_shopstring(0,any)
Address of the phisical shop/office of the company
mccstring(4,4)
Filed is deprected and must be omitted
legal_formstring(0,any)
Legal form of the company
Available Options: sole-trader , limited-company , limited-partnership , limited-liability-partnership , other , self-employed
legal_form_descriptionstring(0,any)
Required when legal_form is specified as other
business_activitystring(0,any)
More details in nomernclutres section
country_of_incorporationstring(0,any)
ISO 3166-1 alpha-2
vat_registrationstring(0,any)
VAT registration number of the company
is_sieboolean
In case the company appears in any sanctions list the field must be marked as true
company_membersarray[object]
first_namestring(0,any)
First name of the member
last_namestring(0,any)
Last name of the member
mobile_phonestring(0,any)
Mobile phone of the member
phonestring(0,any)
Phone of the member
legal_namestring(0,any)
Used when member is other legal entity
uicstring(0,any)
Business registration number.Used when member is other legal entity
countrystring(0,any)
Country of birth or country of legal entity.ISO 3166-1 alpha-2
country_of_residencestring(0,any)
ISO 3166-1 alpha-2
zipstring(0,any)
Postal/Zip code of the member.
citystring(0,any)
City of the member.
address1string(0,any)
Address of the member.
address2string(0,any)
Additional info for the address
countystring(0,any)
Region of the member
ownershipboolean
Only for UBO to specify the percentage of the ownership
ownership_percentageinteger(0,any)
Only for UBO to specify the percentage of the ownership
typearray(1,2)*
Available Options: ubo , ceo , representative , proxy , legal-entity , officer
unique_identifierstring(0,any)
Unique number of persons on offical document.
userstring(0,any)
Existing user in Paynetics system to get KYC details
legal_formstring(0,any)
Legal form of the company
Available Options: sole-trader , limited-company , limited-partnership , limited-liability-partnership , other , self-employed
place_of_birthstring(0,any)
ISO 3166-1 alpha-2
pep_declarationboolean
Mark as PEP
pep_related_declarationboolean
Mark as PEP relative
is_sipboolean
Mark as that appears in sanction lists
birthdaystring(0,any)
Date of birth
nationalitystring(0,any)
ISO 3166-1 alpha-2
contact_emailstring(0,any)
documentsarray[object]
filestring(0,any)
Base64 encoded file
file_typestring(0,any)
Type of the file
Available Options: pdf , docx , xlxs , jpg , jpeg , png , mov , mp4
Welcome to Paynetics' transactions section. Let’s go over the basics.
What is a transaction in Paynetics?
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:
Funds are transferred between two Paynetics accounts by preforming P2P using identifiers (tokens)
IBAN transfers to PATC accounts
Examples for External movements:
Card issued by Paynetics is charged/funded
Wire transfer is performed from/to Paynetics issued IBAN
Types of Transactions
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 IBAN
Transactions List
Endpoint
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)
Details of wire transfer. Required when type is wire-transfer. Conditional for type internal-transfer
sender_namestring(0,any)*
Sender of the transfer
sender_bank_namestring(0,any)
Sender bank name
sender_bank_countrystring(0,any)
Sender bank country
sender_bank_codestring(0,any)
Sender bank code
sender_ibanstring(0,any)*
Sender IBAN
sender_sort_codestring(0,any)
Sender Sort code (GBP transfers)
sender_account_numberstring(0,any)
Sender Account (GBP transfers)
receiver_namestring(0,any)*
Receiver of the transfer
receiver_bankstring(0,any)
Receiver bank name
receiver_ibanstring(0,any)*
Receiver IBAN
receiver_sort_codestring(0,any)
Receiver Sort code (GBP transfers)
receiver_account_numberstring(0,any)
Receiver Account (GBP transfers)
receiver_bank_namestring(0,any)
Receiver bank name
receiver_bank_countrystring(0,any)
Receiver bank country
receiver_bank_codestring(0,any)
Receiver bank code
chargesstring(0,any)
Who pays for charges
Available Options: sha , our , ben
value_datestring(0,any)
Value date of the transfer
settlement_datestring(0,any)
Settlement date of the transfer
statusstring(0,any)
network_original_codestring(0,any)
networkstring(0,any)
is_instantboolean
counterpartobject
Required when type is internal-transfer. Represents the other particiapnt in the transcation.
instancestring(0,any)
merchantstring(0,any)
Conditional in case account is opened to user
userstring(0,any)
Conditional in case account is opened to user
accountstring(0,any)*
Token of the account
balancestring(0,any)*
Token of the balance
external_balancestring(0,any)
Identifier in external processor if available
amountnumber(0,any)*
Amount in balance currency
currencystring(0,any)*
Account balance currency
debit_creditstring(0,any)*
Direction of funds. Debit -> outgoing, Credit -> incoming
Available Options: debit , credit
phonestring(0,any)
Name of the customer.
emailstring(0,any)
Email of the customer.
namestring(0,any)
Name of the customer.
balance_beforenumber(0,any)
Balance of the customer before transaction
balance_afternumber(0,any)
Balance of the customer after transaction
fxnumber(0,any)
FX conversion rate.
Response
Programs
What is a program in Paynetics?
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
What is an account in Paynetics?
Accounts are entities created against a merchant or user with the respective program. They can have one
or multiple balances depending on your program.
Paynetics Account Core Functionalities
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:
via wire transfer from an external bank by IBAN
via external bank card
via internal bank transfer (P2P)
Type of accounts
There are several types of accounts that can be created:
Default
Funding
Virtual
Breakage
Glossary
merchant - all legal entity clients of Paynetics
user - all natural parsons clients of Paynetics
balance - a record of available funds that is always linked with an IBAN or balance token.
Account Creation
How to Create an Account?
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
Request
Structure
programstring(0,any)
merchantstring(0,any)
userstring(0,any)
mainstring(0,any)
skip_iban_generationboolean
aliasstring(0,any)
Request
Response
Structure
codeinteger(0,any)
dataobject
programstring(0,any)
tokenstring(0,any)
merchantstring(0,any)
userstring(0,any)
typestring(0,any)
numberstring(0,any)
link_keystring(0,any)
is_mainboolean
statusstring(0,any)
multicurrencyboolean
balancesarray[object]
availablenumber(0,any)
blockednumber(0,any)
currencystring(0,any)
tokenstring(0,any)
ibanstring(0,any)
sort_codestring(0,any)
account_numberstring(0,any)
numberstring(0,any)
is_mainboolean
Response
Account Status
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
Request
Structure
statusstring(0,any)
Available Options: active , blocked
Request
Response
Structure
codeinteger(0,any)
Response
Endpoint
DELETE
/v2/accounts/{account}
Operation
account_terminate
Parameters
[ account ]
Token from account creation
Response
Structure
codeinteger(0,any)
Response
Account List/Details
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)
Response
Structure
codeinteger(0,any)
dataobject
itemsarray[object]
programstring(0,any)
tokenstring(0,any)
merchantstring(0,any)
userstring(0,any)
typestring(0,any)
numberstring(0,any)
link_keystring(0,any)
is_mainboolean
statusstring(0,any)
multicurrencyboolean
balancesarray[object]
availablenumber(0,any)
blockednumber(0,any)
currencystring(0,any)
tokenstring(0,any)
ibanstring(0,any)
sort_codestring(0,any)
account_numberstring(0,any)
numberstring(0,any)
is_mainboolean
total_itemsinteger(0,any)
Response
Account List/Details
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
Response
Structure
codeinteger(0,any)
dataobject
programstring(0,any)
tokenstring(0,any)
merchantstring(0,any)
userstring(0,any)
typestring(0,any)
numberstring(0,any)
link_keystring(0,any)
is_mainboolean
statusstring(0,any)
multicurrencyboolean
balancesarray[object]
availablenumber(0,any)
blockednumber(0,any)
currencystring(0,any)
tokenstring(0,any)
ibanstring(0,any)
sort_codestring(0,any)
account_numberstring(0,any)
numberstring(0,any)
is_mainboolean
Response
Cards
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
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
Request
Structure
programstring(0,any)
accountstring(0,any)
merchantstring(0,any)
Required only for non pesonalized card in case must be assigned to merchant immediately.
userstring(0,any)
Required only for non pesonalized card in case must be assigned to user immediately.
amlstring(0,any)
Token of AML check. Conditinal: depending on program configuration
emboss_namestring(0,any)
emboss_name_line4string(0,any)
fulfil1string(0,any)
fulfil2string(0,any)
thermal_line1string(0,any)
thermal_line2string(0,any)
activeboolean
pinstring(0,any)
typestring(0,any)
Available Options: plastic , virtual
first_namestring(0,any)
last_namestring(0,any)
aliasstring(0,any)
delivery_detailsobject
citystring(0,any)
countrystring(0,any)
countystring(0,any)
zipstring(0,any)
address1string(0,any)
address2string(0,any)
address3string(0,any)
methodstring(0,any)
codestring(0,any)
mobile_phonestring(0,any)
three_domain_enrolmentobject
otp_smsstring(0,any)
biometricboolean
urlstring(0,any)
Request
Response
Structure
codeinteger(0,any)
dataobject
programstring(0,any)
tokenstring(0,any)
merchantstring(0,any)
userstring(0,any)
typestring(0,any)
numberstring(0,any)
link_keystring(0,any)
is_mainboolean
statusstring(0,any)
multicurrencyboolean
balancesarray[object]
availablenumber(0,any)
blockednumber(0,any)
currencystring(0,any)
tokenstring(0,any)
ibanstring(0,any)
sort_codestring(0,any)
account_numberstring(0,any)
numberstring(0,any)
is_mainboolean
Response
Card Details Update
Endpoint
PUT
/v2/cards/{card}
Operation
card_update
Parameters
[ card ]
Request
Structure
merchantstring(0,any)
Required only for non pesonalized card in case must be assigned to merchant immediately.
userstring(0,any)
Required only for non pesonalized card in case must be assigned to user immediately.
emboss_namestring(0,any)
mobile_phonestring(0,any)
first_namestring(0,any)
last_namestring(0,any)
delivery_detailsobject
citystring(0,any)
countrystring(0,any)
countystring(0,any)
zipstring(0,any)
address1string(0,any)
address2string(0,any)
address3string(0,any)
branch_codestring(0,any)
expiration_monthstring(0,any)
expiration_yearstring(0,any)
Request
Response
Structure
codeinteger(0,any)
Response
Card Conversion
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
Response
Structure
codeinteger(0,any)
Response
Card Activation
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
Request
Structure
amlstring(0,any)
Conditional: For some cases for non personalized cards.
Request
Response
Structure
codeinteger(0,any)
Response
Card Status and Termination
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
Request
Structure
statusstring(0,any)
Available Options: active , inactive
Request
Response
Structure
codeinteger(0,any)
Response
Endpoint
DELETE
/v2/cards/{card}
Operation
card_terminate
Parameters
[ card ]
Token from card creation
Response
Structure
codeinteger(0,any)
Response
Card Renew
Endpoint
PUT
/v2/cards/{card}/renew
Operation
card_renew
Parameters
[ card ]
Request
Structure
modeinteger(0,any)
Request
Response
Structure
codeinteger(0,any)
Response
Card Limits and Fees
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
Response
Structure
codeinteger(0,any)
dataobject
usagestring(0,any)
feesstring(0,any)
schedule_feesstring(0,any)
web_service_feesstring(0,any)
limitsstring(0,any)
linkagestring(0,any)
mccstring(0,any)
whiteliststring(0,any)
Response
Endpoint
PUT
/v2/cards/{card}/groups
Operation
card_groups
Parameters
[ card ]
Token from card creation
Request
Structure
usagestring(0,any)
feesstring(0,any)
schedule_feesstring(0,any)
web_service_feesstring(0,any)
limitsstring(0,any)
linkagestring(0,any)
mccstring(0,any)
whiteliststring(0,any)
Request
Response
Structure
codeinteger(0,any)
Response
List / detail
Endpoint
GET
/v2/cards/{page}/{limit}
Operation
cards_list
Parameters
[ page ]
[ limit ]
Filters
merchant - (Token of merchant)
user - (Token of user)
Response
Structure
codeinteger(0,any)
dataobject
itemsarray[object]
tokenstring(0,any)
typestring(0,any)
is_digitalizedboolean
is_activatedboolean
is_otp_sms_enabledboolean
is_bio_enabledboolean
external_identifierstring(0,any)
statusstring(0,any)
branch_codestring(0,any)
delivery_detailsobject
countrystring(0,any)
countystring(0,any)
citystring(0,any)
zipstring(0,any)
address1string(0,any)
address2string(0,any)
address3string(0,any)
mobile_phonestring(0,any)
first_namestring(0,any)
last_namestring(0,any)
is_issuedboolean
userstring(0,any)
merchantstring(0,any)
first_namestring(0,any)
last_namestring(0,any)
emboss_namestring(0,any)
emboss_name_line4string(0,any)
total_itemsinteger(0,any)
Response
Endpoint
GET
/v2/cards/{card}
Operation
card_details
Parameters
[ card ]
Token from card creation
[ card ]
Token from card creation
Response
Structure
codeinteger(0,any)
dataobject
tokenstring(0,any)
typestring(0,any)
is_digitalizedboolean
is_activatedboolean
is_otp_sms_enabledboolean
is_bio_enabledboolean
external_identifierstring(0,any)
statusstring(0,any)
branch_codestring(0,any)
delivery_detailsobject
countrystring(0,any)
countystring(0,any)
citystring(0,any)
zipstring(0,any)
address1string(0,any)
address2string(0,any)
address3string(0,any)
mobile_phonestring(0,any)
first_namestring(0,any)
last_namestring(0,any)
is_issuedboolean
userstring(0,any)
merchantstring(0,any)
first_namestring(0,any)
last_namestring(0,any)
emboss_namestring(0,any)
emboss_name_line4string(0,any)
Response
Number & CVV
Endpoint
GET
/v2/cards/{card}/first-half
Operation
card_number
Parameters
[ card ]
Token from card creation
Response
Structure
codeinteger(0,any)
dataobject
panstring(0,any)
expiration_monthstring(0,any)
expiration_yearstring(0,any)
Response
Endpoint
GET
/v2/cards/{card}/second-half
Operation
card_number
Parameters
[ card ]
Token from card creation
Response
Structure
codeinteger(0,any)
dataobject
panstring(0,any)
cvvstring(0,any)
Response
Card PIN Management
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
Response
Structure
codeinteger(0,any)
dataobject
pinstring(0,any)
PIN of the card
Response
Card PIN
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
Response
Structure
codeinteger(0,any)
Response
Card PIN & CVV
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
Response
Structure
codeinteger(0,any)
Response
Card 3DS Enrollment
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
Request
Structure
otp_smsstring(0,any)
biometricboolean
Request
Response
Structure
codeinteger(0,any)
Response
Enrolment mobile phone
* number can be amended at a later stage.
Endpoint
PUT
/v2/cards/{card}/3ds
Operation
card_3ds_update
Parameters
[ card ]
Token from card creation
Request
Structure
otp_smsstring(0,any)
Request
Response
Structure
codeinteger(0,any)
Response
Enrolment for both types
* 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
Request
Structure
typestring(0,any)
Request
Response
Structure
codeinteger(0,any)
Response
Process biometric 3ds
Endpoint
POST
/v2/cards/{card}/3ds/process
Operation
card_3ds_process
Parameters
[ card ]
Request
Structure
requeststring(0,any)
statusstring(0,any)
Available Options: SUCCESS , FAILURE
Request
Response
Structure
codeinteger(0,any)
Response
Card Provisioning
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.
Process Apple Encryption
Endpoint
POST
/v2/cards/{card}/apple/encrypt
Operation
enc_card
Parameters
[ card ]
Token from card creation
Response
Structure
codeinteger(0,any)
dataobject
encryption_pass_datastring(0,any)
activation_datastring(0,any)
ephemeral_public_keystring(0,any)
Response
Process Google Encryption
Endpoint
POST
/v2/cards/{card}/google/encrypt
Operation
enc_card
Parameters
[ card ]
Token from card creation
Response
Structure
codeinteger(0,any)
dataobject
opcstring(0,any)
addressobject
card_typestring(0,any)
real_namestring(0,any)
Response
Card Tokens
Endpoint
GET
/v2/cards/{card}/tokens/{deviceId}
Operation
card_tokens
Parameters
[ card ]
Token from card creation
[ deviceId ]
Device ID
Response
Structure
codeinteger(0,any)
dataobject
card_tokensstring(0,any)
Response
Transfers
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
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.
Wire Transfers
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
Request
Structure
amountnumber(0,any)
Amount to be deducted from customer account
currencystring(0,any)
Available Options: EUR , BGN , GBP
codestring(0,any)
linkstring(0,any)
Link to another transaction
referencestring(0,any)
reference2string(0,any)
reference3string(0,any)
reference4string(0,any)
origin_of_fundsstring(0,any)
Available Options:
descriptionstring(0,any)
is_instantboolean
Only for SEPA transfers (EUR)
skip_feesboolean
Option for skiping fees.
debtorobject
Sender of the funds
balancestring(0,any)
Balance token of the customer
external_identifierstring(0,any)
GPS Public token
ibanstring(0,any)
Valid IBAN
sort_codestring(6,6)
Valid sort code
account_numberstring(8,8)
Valid account number
addressstring(0,any)
Address of legal entity or natural person. Required of absent in customer profile on registration!
namestring(0,any)
Name of legal entity or natural person. Required of absent in customer profile on registration!
countrystring(0,any)
Country of legal entity or natural person. Required of absent in customer profile on registration!
creditorobject
Receiver of the funds
balancestring(0,any)
Balance token of the customer
external_identifierstring(0,any)
GPS Public token
ibanstring(0,any)
Valid IBAN
sort_codestring(6,6)
Valid sort code
account_numberstring(8,8)
Valid account number
addressstring(0,any)
Address of legal entity or natural person. Required of absent in customer profile on registration!
namestring(0,any)
Name of legal entity or natural person. Required of absent in customer profile on registration!
countrystring(0,any)
Country of legal entity or natural person. Required of absent in customer profile on registration!
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
Queue
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)
Address of legal entity or natural person. Required of absent in customer profile on registration!
namestring(0,any)
Name of legal entity or natural person. Required of absent in customer profile on registration!
countrystring(0,any)
Country of legal entity or natural person. Required of absent in customer profile on registration!
creditorobject
Receiver of the funds
balancestring(0,any)
Balance token of the customer
external_identifierstring(0,any)
GPS Public token
ibanstring(0,any)
Valid IBAN
sort_codestring(6,6)
Valid sort code
account_numberstring(8,8)
Valid account number
addressstring(0,any)
Address of legal entity or natural person. Required of absent in customer profile on registration!
namestring(0,any)
Name of legal entity or natural person. Required of absent in customer profile on registration!
countrystring(0,any)
Country of legal entity or natural person. Required of absent in customer profile on registration!
copstring(0,any)
Confirmatino of Payee token
Request
Response
Structure
codeinteger(0,any)
dataobject
tokenstring(0,any)
Token from operation
Response
Card SDK
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
Operation
Web hooks
Merchant created
Merchant risk score
Account iban
Transaction new
Transaction update
Balance update
Transaction Suspended
Postman Collection
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.
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.
3. Configuration
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
3. Usage and Guidelines
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.
For legal entities onboarding after successful request
tokens of the application and company members will added as variables for subsequent requests.
For natural persons onboarding after successful request
user token will be added as variable which can be used for sub requests.
For account creation you can add program as variable in collection or replace it on each request.
After successful account creation account token will be added as variable and can be used for sub requests.
For non personalized card creation you can add program as variable in collection or replace it on each request.
After successful card creation account card will be added as variable and can be used for sub requests.
For transfers you will need either debtor/creditor identifiers of the balances or for external transfers valid creditor IBAN/AccountNumber and Sort Code.
For all API which return list of entities like transactions list, accounts list etc, you can find all available filters in Params section of the request.