You are now

!

Introduction

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-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:

  • 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.

Example

X-Request-Id : 20be1835-85fb-4932-a986-a6b5fbe6b648

Onboarding

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 Process Overview

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

merchant string (32,36)

Master Merchant token

products array (1,5) *

Available Options: pos , e-commerce , qr , account-opening , card-issuing

due_diligence string (0,any)

Available Options: SDD , CDD

company object

Company Details

trade_name string (0,any)

Doing business as

legal_name string (0,any)

Legal name as appears in trade reigster

uic string (0,any)

Business Registration Number

incorporation_date string (0,any)

Date of the company incorporation

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

mcc string (4,4)

Filed is deprected and must be omitted

legal_form string (0,any)

Legal form of the company

Available Options: sole-trader , limited-company , limited-partnership , limited-liability-partnership , other , self-employed

legal_form_description string (0,any)

Required when legal_form is specified as other

business_activity string (0,any)

More details in nomernclutres section

country_of_incorporation string (0,any)

ISO 3166-1 alpha-2

vat_registration string (0,any)

VAT registration number of the company

is_sie boolean

In case the company appears in any sanctions list the field must be marked as true

company_members array[object]

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 , officer

unique_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-employed

place_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 , mp4

document_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-report

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 , mp4

document_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-report

acquiring object

Details for e-commerce/pos products

pos object

Details for pos product

fee_group string (0,any)

Predifined fee group provided by Paynetics in advance

projected_monthly_value number (0,any)

In EUR

descriptor string (0,any)

Card Acceptor Name

ecommerce object

Details for e-commerce product

register3ds boolean

supported_authorization_types array (0,any)

Available Options: moto , recurring , pay-by-link , oct

fee_group string (0,any)

projected_monthly_value number (0,any)

descriptor string (0,any)

payout_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

questionnaire object

Futher questions for the company

is_online boolean

Must be mark as true when customer is doing business online

has_offshore_clients boolean

Must be mark as true when customer has client from off shore zone

make_business_with_san boolean

Must be mark as true when customer is doing business with legal entities/natural persions in sanction lists

has_kyc_procedure boolean

Must be mark as true when customer has KYC procedure for their customers

has_kyc_procedure_description string (0,any)

The KYC procedure must be specified.

require_additional_licenses boolean

Must be mark as true when customer must provide addtional license

maintains_accounts_on_behalf_of_clients boolean

Must be mark as true when customer maiting other legal entities or naturual persons bank accounts

perform_transactions_on_behalf_of_clients boolean

Must be mark as true when customer is performing transaction onbehalf of other egal entities or naturual persons

is_off_shore boolean

Must be mark as true when customer is from offshore zone

purpose_of_usage string (0,any)

Must specify how the requested product will be used

source_of_funds string (0,any)

Source of funds of the company

Available Options: dividends , donation , funds_from_other_auxiliary_sources , inheritance , loan_from_financial_institutions , loan_from_third_parties , ordinary_business_activity , origin_of_funds_unknown , other , rent , sale_of_company_shares_or_business , sale_of_movable_assets , sale_of_real_estate

months_of_doing_business integer (0,any)

For how long the company is oprerational

projected_monthly_volume number (0,any)

Projected volume in EUR the company will make each month

ip_address string (0,any)

IP Address of customer submitted application

fingerprint string (0,any)

Device fingerprint of the customer submitted application

Request


                   
               

Response Structure

code integer (0,any)

data object

token string (0,any)

UUID of the application

company object

token string (0,any)

UUID of the company

company_members array[object]

token string (0,any)

UUID of company member

first_name string (0,any)

Name of company member

last_name string (0,any)

Name of company member

Response


                    
                

Errors

11001

Validation error

11008

Validator configuration not found

Company Details

You can add or change company details via Paynetics' API. Supported operations:

  • Add documents
  • Change contact details
  • Add/Suspend company members
  • Add documents related to company members

Please refer to the example for how to change company details.

Updating Company Details

Endpoint

PUT   /v3/applications/{application}/companies

Operation

company_update

Parameters

[ application ]

Request Structure

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


                   
               

Response Structure

code integer (0,any)

Response


                    
                

Errors

11001

Validation error

11002

Application not found

Adding Company Document

Endpoint

POST   /v3/applications/{application}/companies/documents

Operation

company_add_document

Parameters

[ application ]

Request Structure

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 , mp4

document_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-report

Request


                   
               

Response Structure

code integer (0,any)

Response


                    
                

Errors

11001

Validation error

11002

Application not found

Adding Company member

Endpoint

POST   /v3/applications/{application}/companies/members

Operation

company_add_member

Parameters

[ application ]

Request Structure

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 , officer

unique_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-employed

place_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 , mp4

document_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-report

Request


                   
               

Response Structure

code integer (0,any)

data object

token string (0,any)

UUID of the application

company object

token string (0,any)

UUID of the company

company_members array[object]

token string (0,any)

UUID of company member

first_name string (0,any)

Name of company member

last_name string (0,any)

Name of company member

Response


                    
                

Errors

11001

Validation error

11002

Application not found

Updating Company member

Endpoint

PUT   /v3/applications/{application}/companies/members/{token}

Operation

company_member_update

Parameters

[ application ]

[ token ]

Request Structure

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-employed

pep_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 , inactive

Request


                   
               

Response Structure

code integer (0,any)

Response


                    
                

Errors

11001

Validation error

11002

Company member not found

KYC Init

Endpoint

POST   /v1/kyc

Operation

kyc_init

Request Structure

user string (0,any)

Token of the user

Request


                   
               

Response Structure

code integer (0,any)

data object

identification string (0,any)

short_code string (0,any)

Response


                    
                

Errors

11002

payoo.users.not_found

Add Company member document

Endpoint

POST   /v3/applications/{application}/companies/members/{token}/documents

Operation

company_member_add_document

Parameters

[ application ]

[ token ]

Request Structure

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 , mp4

document_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-report

Request


                   
               

Response Structure

code integer (0,any)

Response


                    
                

Errors

11001

Validation error

11002

Company member not found

Create Natural Person

Endpoint

POST   /v2/users

Operation

user_create

Request Structure

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 , default

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 , mp4

document_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-report

company string (0,any)

Request


                   
               

Update Natural Person

Endpoint

PUT   /v2/users/{user}

Operation

user_update

Parameters

[ user ]

Token from user creation

Request Structure

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


                   
               

Response Structure

code integer (0,any)

Response


                    
                

Get Details of Natural Person

Endpoint

GET   /v2/users/{user}

Operation

user_details

Parameters

[ user ]

Token from user creation

Response Structure

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 , default

Response


                    
                

Remove Natural Person

Endpoint

DELETE   /v2/users/{user}

Operation

user_remove

Parameters

[ user ]

Token from user creation

Response Structure

code integer (0,any)

Response


                    
                

Add Natural Person Document

Endpoint

POST   /v2/users/{user}/documents

Operation

user_add_document

Parameters

[ user ]

Request Structure

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 , mp4

document_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-report

Request


                   
               

Response Structure

code integer (0,any)

data object

token string (0,any)

Token from operation

Response


                    
                

Errors

11001

Validation error

11002

Application not found

AML Natural Persons

You can check AML and sanctions presence:


AML Check

Endpoint

POST   /v1/aml

Operation

aml_check

Request Structure

first_name string (0,any)

last_name string (0,any)

nationality string (0,any)

birthday string (0,any)

Request


                   
               

Response Structure

code integer (0,any)

data object

token string (0,any)

Token from operation

Response


                    
                

Errors

18000

services.general.invalid_processor

18001

service.aml.match.found


Transactions

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)

Response Structure

code integer (0,any)

data object

items array[object]

token string (0,any) *

Unique identifier of the transaction

merchant string (0,any)

Conditional in case account is opened to user

user string (0,any)

Conditional in case account is opened to user

account string (0,any) *

Token of the account

balance string (0,any) *

Token of the balance

external_balance string (0,any)

Identifier in external processor if available

channel string (0,any)

type string (0,any) *

Type of the transaction

Available Options: internal-transfer , load , wire-transfer , authorization , pre-authorization , capture , purchase , refund , reversal , credit , fee , oct , presentment

amount number (0,any) *

Amount in balance currency

currency string (0,any) *

Account balance currency

original_amount number (0,any) *

Original amount of the transaction

original_currency string (0,any) *

Original currency of the transaction

name string (0,any)

Name of the customer.

phone string (0,any)

Name of the customer.

email string (0,any)

Email of the customer.

balance_before number (0,any)

Balance of the customer before transaction

balance_after number (0,any)

Balance of the customer after transaction

debit_credit string (0,any) *

Direction of funds. Debit -> outgoing, Credit -> incoming

Available Options: debit , credit

linked_transaction string (0,any)

Link of different type of transactions. Authorizaions - Presentments. Authorizations - Reveresal etc

external_identifier string (0,any)

Identifier in external system

external_link string (0,any)

Link of different card authorization and presentments. Can be any type of length.

fee string (0,any)

General fee for the opreration in account currency

status string (0,any)

Status of the transaction. 1 - Processed, 0 - Pending, -1 - Failed, -2 - Cancelled

Available Options: 1 , 0 , -1 , -2

reference string (0,any)

Reference coming from external source or set by customer for transfers

reference2 string (0,any)

Reference coming from external source or set by customer for transfers

reference3 string (0,any)

Reference coming from external source

reference4 string (0,any)

Reference coming from external source

description string (0,any)

Description of the transaction

is_recurring boolean

Applicable for transactions which are marked to be recurring event

is_initial_recurring boolean

authorizations array (0,any)

created_at string (0,any)

Date of the transaction creation

updated_on string (0,any)

Date of the transaction last update

execution_date string (0,any)

Date of the transaction processing

acquiring object

card string (0,any)

card_pan_obfuscated string (0,any)

card_type string (0,any)

ccti_id string (0,any)

transaction_stamp string (0,any)

pos_terminal_id string (0,any)

processing_code string (0,any)

point_of_service_entry_mode string (0,any)

acquiring_institution_identification_code string (0,any)

card_acceptor_identification_code string (0,any)

card_acceptor_name string (0,any)

card_acceptor_city string (0,any)

card_acceptor_country string (0,any)

system_trace_audit_number string (0,any)

is_captured boolean

authorization_code string (0,any)

retrieval_reference_number string (0,any)

is3d boolean

is_moto boolean

mcc string (0,any)

mcc_description string (0,any)

fx_fixed_fee string (0,any)

fx_fee_rate string (0,any)

fx_rate string (0,any)

domestic_fee string (0,any)

domestic_rate string (0,any)

non_domestic_fee string (0,any)

non_domestic_rate string (0,any)

token_unique_reference string (0,any)

approval_code string (0,any)

authorization_date string (0,any)

authorization_type string (0,any)

note string (0,any)

description string (0,any)

wires object

Details of wire transfer. Required when type is wire-transfer. Conditional for type internal-transfer

sender_name string (0,any) *

Sender of the transfer

sender_bank_name string (0,any)

Sender bank name

sender_bank_country string (0,any)

Sender bank country

sender_bank_code string (0,any)

Sender bank code

sender_iban string (0,any) *

Sender IBAN

sender_sort_code string (0,any)

Sender Sort code (GBP transfers)

sender_account_number string (0,any)

Sender Account (GBP transfers)

receiver_name string (0,any) *

Receiver of the transfer

receiver_bank string (0,any)

Receiver bank name

receiver_iban string (0,any) *

Receiver IBAN

receiver_sort_code string (0,any)

Receiver Sort code (GBP transfers)

receiver_account_number string (0,any)

Receiver Account (GBP transfers)

receiver_bank_name string (0,any)

Receiver bank name

receiver_bank_country string (0,any)

Receiver bank country

receiver_bank_code string (0,any)

Receiver bank code

charges string (0,any)

Who pays for charges

Available Options: sha , our , ben

value_date string (0,any)

Value date of the transfer

settlement_date string (0,any)

Settlement date of the transfer

status string (0,any)

network_original_code string (0,any)

network string (0,any)

is_instant boolean

counterpart object

Required when type is internal-transfer. Represents the other particiapnt in the transcation.

instance string (0,any)

merchant string (0,any)

Conditional in case account is opened to user

user string (0,any)

Conditional in case account is opened to user

account string (0,any) *

Token of the account

balance string (0,any) *

Token of the balance

external_balance string (0,any)

Identifier in external processor if available

amount number (0,any) *

Amount in balance currency

currency string (0,any) *

Account balance currency

debit_credit string (0,any) *

Direction of funds. Debit -> outgoing, Credit -> incoming

Available Options: debit , credit

phone string (0,any)

Name of the customer.

email string (0,any)

Email of the customer.

name string (0,any)

Name of the customer.

balance_before number (0,any)

Balance of the customer before transaction

balance_after number (0,any)

Balance of the customer after transaction

fx number (0,any)

FX conversion rate.

total_items integer (0,any)

Response


                    
                

Transaction Details

Endpoint

GET   /v2/transactions/{transaction}

Operation

transaction_details

Parameters

[ transaction ]

Response Structure

code integer (0,any)

data object

token string (0,any) *

Unique identifier of the transaction

merchant string (0,any)

Conditional in case account is opened to user

user string (0,any)

Conditional in case account is opened to user

account string (0,any) *

Token of the account

balance string (0,any) *

Token of the balance

external_balance string (0,any)

Identifier in external processor if available

channel string (0,any)

type string (0,any) *

Type of the transaction

Available Options: internal-transfer , load , wire-transfer , authorization , pre-authorization , capture , purchase , refund , reversal , credit , fee , oct , presentment

amount number (0,any) *

Amount in balance currency

currency string (0,any) *

Account balance currency

original_amount number (0,any) *

Original amount of the transaction

original_currency string (0,any) *

Original currency of the transaction

name string (0,any)

Name of the customer.

phone string (0,any)

Name of the customer.

email string (0,any)

Email of the customer.

balance_before number (0,any)

Balance of the customer before transaction

balance_after number (0,any)

Balance of the customer after transaction

debit_credit string (0,any) *

Direction of funds. Debit -> outgoing, Credit -> incoming

Available Options: debit , credit

linked_transaction string (0,any)

Link of different type of transactions. Authorizaions - Presentments. Authorizations - Reveresal etc

external_identifier string (0,any)

Identifier in external system

external_link string (0,any)

Link of different card authorization and presentments. Can be any type of length.

fee string (0,any)

General fee for the opreration in account currency

status string (0,any)

Status of the transaction. 1 - Processed, 0 - Pending, -1 - Failed, -2 - Cancelled

Available Options: 1 , 0 , -1 , -2

reference string (0,any)

Reference coming from external source or set by customer for transfers

reference2 string (0,any)

Reference coming from external source or set by customer for transfers

reference3 string (0,any)

Reference coming from external source

reference4 string (0,any)

Reference coming from external source

description string (0,any)

Description of the transaction

is_recurring boolean

Applicable for transactions which are marked to be recurring event

is_initial_recurring boolean

authorizations array (0,any)

created_at string (0,any)

Date of the transaction creation

updated_on string (0,any)

Date of the transaction last update

execution_date string (0,any)

Date of the transaction processing

acquiring object

card string (0,any)

card_pan_obfuscated string (0,any)

card_type string (0,any)

ccti_id string (0,any)

transaction_stamp string (0,any)

pos_terminal_id string (0,any)

processing_code string (0,any)

point_of_service_entry_mode string (0,any)

acquiring_institution_identification_code string (0,any)

card_acceptor_identification_code string (0,any)

card_acceptor_name string (0,any)

card_acceptor_city string (0,any)

card_acceptor_country string (0,any)

system_trace_audit_number string (0,any)

is_captured boolean

authorization_code string (0,any)

retrieval_reference_number string (0,any)

is3d boolean

is_moto boolean

mcc string (0,any)

mcc_description string (0,any)

fx_fixed_fee string (0,any)

fx_fee_rate string (0,any)

fx_rate string (0,any)

domestic_fee string (0,any)

domestic_rate string (0,any)

non_domestic_fee string (0,any)

non_domestic_rate string (0,any)

token_unique_reference string (0,any)

approval_code string (0,any)

authorization_date string (0,any)

authorization_type string (0,any)

note string (0,any)

description string (0,any)

wires object

Details of wire transfer. Required when type is wire-transfer. Conditional for type internal-transfer

sender_name string (0,any) *

Sender of the transfer

sender_bank_name string (0,any)

Sender bank name

sender_bank_country string (0,any)

Sender bank country

sender_bank_code string (0,any)

Sender bank code

sender_iban string (0,any) *

Sender IBAN

sender_sort_code string (0,any)

Sender Sort code (GBP transfers)

sender_account_number string (0,any)

Sender Account (GBP transfers)

receiver_name string (0,any) *

Receiver of the transfer

receiver_bank string (0,any)

Receiver bank name

receiver_iban string (0,any) *

Receiver IBAN

receiver_sort_code string (0,any)

Receiver Sort code (GBP transfers)

receiver_account_number string (0,any)

Receiver Account (GBP transfers)

receiver_bank_name string (0,any)

Receiver bank name

receiver_bank_country string (0,any)

Receiver bank country

receiver_bank_code string (0,any)

Receiver bank code

charges string (0,any)

Who pays for charges

Available Options: sha , our , ben

value_date string (0,any)

Value date of the transfer

settlement_date string (0,any)

Settlement date of the transfer

status string (0,any)

network_original_code string (0,any)

network string (0,any)

is_instant boolean

counterpart object

Required when type is internal-transfer. Represents the other particiapnt in the transcation.

instance string (0,any)

merchant string (0,any)

Conditional in case account is opened to user

user string (0,any)

Conditional in case account is opened to user

account string (0,any) *

Token of the account

balance string (0,any) *

Token of the balance

external_balance string (0,any)

Identifier in external processor if available

amount number (0,any) *

Amount in balance currency

currency string (0,any) *

Account balance currency

debit_credit string (0,any) *

Direction of funds. Debit -> outgoing, Credit -> incoming

Available Options: debit , credit

phone string (0,any)

Name of the customer.

email string (0,any)

Email of the customer.

name string (0,any)

Name of the customer.

balance_before number (0,any)

Balance of the customer before transaction

balance_after number (0,any)

Balance of the customer after transaction

fx number (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

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


                   
               

Response Structure

code integer (0,any)

data object

program string (0,any)

token string (0,any)

merchant string (0,any)

user string (0,any)

type string (0,any)

number string (0,any)

link_key string (0,any)

is_main boolean

status string (0,any)

multicurrency boolean

balances array[object]

available number (0,any)

blocked number (0,any)

currency string (0,any)

token string (0,any)

iban string (0,any)

sort_code string (0,any)

account_number string (0,any)

number string (0,any)

is_main boolean

Response


                    
                

Endpoint

PUT   /v2/accounts/{account}/status

Operation

account_status

Parameters

[ account ]

Token from account creation

Request Structure

status string (0,any)

Available Options: active , blocked

Request


                   
               

Response Structure

code integer (0,any)

Response


                    
                

Endpoint

DELETE   /v2/accounts/{account}

Operation

account_terminate

Parameters

[ account ]

Token from account creation

Response Structure

code integer (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

code integer (0,any)

data object

items array[object]

program string (0,any)

token string (0,any)

merchant string (0,any)

user string (0,any)

type string (0,any)

number string (0,any)

link_key string (0,any)

is_main boolean

status string (0,any)

multicurrency boolean

balances array[object]

available number (0,any)

blocked number (0,any)

currency string (0,any)

token string (0,any)

iban string (0,any)

sort_code string (0,any)

account_number string (0,any)

number string (0,any)

is_main boolean

total_items integer (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

code integer (0,any)

data object

program string (0,any)

token string (0,any)

merchant string (0,any)

user string (0,any)

type string (0,any)

number string (0,any)

link_key string (0,any)

is_main boolean

status string (0,any)

multicurrency boolean

balances array[object]

available number (0,any)

blocked number (0,any)

currency string (0,any)

token string (0,any)

iban string (0,any)

sort_code string (0,any)

account_number string (0,any)

number string (0,any)

is_main boolean

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

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 , virtual

first_name string (0,any)

last_name string (0,any)

alias string (0,any)

delivery_details object

city string (0,any)

country string (0,any)

county string (0,any)

zip string (0,any)

address1 string (0,any)

address2 string (0,any)

address3 string (0,any)

method string (0,any)

code string (0,any)

mobile_phone string (0,any)

three_domain_enrolment object

otp_sms string (0,any)

biometric boolean

url string (0,any)

Request


                   
               

Response Structure

code integer (0,any)

data object

program string (0,any)

token string (0,any)

merchant string (0,any)

user string (0,any)

type string (0,any)

number string (0,any)

link_key string (0,any)

is_main boolean

status string (0,any)

multicurrency boolean

balances array[object]

available number (0,any)

blocked number (0,any)

currency string (0,any)

token string (0,any)

iban string (0,any)

sort_code string (0,any)

account_number string (0,any)

number string (0,any)

is_main boolean

Response


                    
                

Card Details Update

Endpoint

PUT   /v2/cards/{card}

Operation

card_update

Parameters

[ card ]

Request Structure

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)

delivery_details object

city string (0,any)

country string (0,any)

county string (0,any)

zip string (0,any)

address1 string (0,any)

address2 string (0,any)

address3 string (0,any)

branch_code string (0,any)

expiration_month string (0,any)

expiration_year string (0,any)

Request


                   
               

Response Structure

code integer (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

code integer (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

aml string (0,any)

Conditional: For some cases for non personalized cards.

Request


                   
               

Response Structure

code integer (0,any)

Response


                    
                

Card Status and Termination

There are 3 statuses that a card can have:

Endpoint

PUT   /v2/cards/{card}/status

Operation

card_status

Parameters

[ card ]

Token from card creation

Request Structure

status string (0,any)

Available Options: active , inactive

Request


                   
               

Response Structure

code integer (0,any)

Response


                    
                

Endpoint

DELETE   /v2/cards/{card}

Operation

card_terminate

Parameters

[ card ]

Token from card creation

Response Structure

code integer (0,any)

Response


                    
                

Card Renew

Endpoint

PUT   /v2/cards/{card}/renew

Operation

card_renew

Parameters

[ card ]

Request Structure

mode integer (0,any)

Request


                   
               

Response Structure

code integer (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

code integer (0,any)

data object

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)

Response


                    
                

Endpoint

PUT   /v2/cards/{card}/groups

Operation

card_groups

Parameters

[ card ]

Token from card creation

Request Structure

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


                   
               

Response Structure

code integer (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

code integer (0,any)

data object

items array[object]

token string (0,any)

type string (0,any)

is_digitalized boolean

is_activated boolean

is_otp_sms_enabled boolean

is_bio_enabled boolean

external_identifier string (0,any)

status string (0,any)

branch_code string (0,any)

delivery_details object

country string (0,any)

county string (0,any)

city string (0,any)

zip string (0,any)

address1 string (0,any)

address2 string (0,any)

address3 string (0,any)

mobile_phone string (0,any)

first_name string (0,any)

last_name string (0,any)

is_issued boolean

user string (0,any)

merchant string (0,any)

first_name string (0,any)

last_name string (0,any)

emboss_name string (0,any)

emboss_name_line4 string (0,any)

total_items integer (0,any)

Response


                    
                

Endpoint

GET   /v2/cards/{card}

Operation

card_details

Parameters

[ card ]

Token from card creation

[ card ]

Token from card creation

Response Structure

code integer (0,any)

data object

token string (0,any)

type string (0,any)

is_digitalized boolean

is_activated boolean

is_otp_sms_enabled boolean

is_bio_enabled boolean

external_identifier string (0,any)

status string (0,any)

branch_code string (0,any)

delivery_details object

country string (0,any)

county string (0,any)

city string (0,any)

zip string (0,any)

address1 string (0,any)

address2 string (0,any)

address3 string (0,any)

mobile_phone string (0,any)

first_name string (0,any)

last_name string (0,any)

is_issued boolean

user string (0,any)

merchant string (0,any)

first_name string (0,any)

last_name string (0,any)

emboss_name string (0,any)

emboss_name_line4 string (0,any)

Response


                    
                

Number & CVV

Endpoint

GET   /v2/cards/{card}/first-half

Operation

card_number

Parameters

[ card ]

Token from card creation

Response Structure

code integer (0,any)

data object

pan string (0,any)

expiration_month string (0,any)

expiration_year string (0,any)

Response


                    
                

Endpoint

GET   /v2/cards/{card}/second-half

Operation

card_number

Parameters

[ card ]

Token from card creation

Response Structure

code integer (0,any)

data object

pan string (0,any)

cvv string (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

code integer (0,any)

data object

pin string (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

code integer (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

code integer (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_sms string (0,any)

biometric boolean

Request


                   
               

Response Structure

code integer (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_sms string (0,any)

Request


                   
               

Response Structure

code integer (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

type string (0,any)

Request


                   
               

Response Structure

code integer (0,any)

Response


                    
                

Process biometric 3ds

Endpoint

POST   /v2/cards/{card}/3ds/process

Operation

card_3ds_process

Parameters

[ card ]

Request Structure

request string (0,any)

status string (0,any)

Available Options: SUCCESS , FAILURE

Request


                   
               

Response Structure

code integer (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

code integer (0,any)

data object

encryption_pass_data string (0,any)

activation_data string (0,any)

ephemeral_public_key string (0,any)

Response


                    
                

Process Google Encryption

Endpoint

POST   /v2/cards/{card}/google/encrypt

Operation

enc_card

Parameters

[ card ]

Token from card creation

Response Structure

code integer (0,any)

data object

opc string (0,any)

address object

card_type string (0,any)

real_name string (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

code integer (0,any)

data object

card_tokens string (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

amount number (0,any)

Amount to be deducted from customer account

currency string (0,any)

Available Options: EUR , BGN , GBP

code 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)

debtor object

Sender of the funds

balance string (0,any)

Balance token of the customer

external_identifier string (0,any)

GPS Public token

iban string (0,any)

Valid IBAN

sort_code string (6,6)

Valid sort code

account_number string (8,8)

Valid account number

address string (0,any)

Address of legal entity or natural person. Required of absent in customer profile on registration!

name string (0,any)

Name of legal entity or natural person. Required of absent in customer profile on registration!

country string (0,any)

Country of legal entity or natural person. Required of absent in customer profile on registration!

creditor object

Receiver of the funds

balance string (0,any)

Balance token of the customer

external_identifier string (0,any)

GPS Public token

iban string (0,any)

Valid IBAN

sort_code string (6,6)

Valid sort code

account_number string (8,8)

Valid account number

address string (0,any)

Address of legal entity or natural person. Required of absent in customer profile on registration!

name string (0,any)

Name of legal entity or natural person. Required of absent in customer profile on registration!

country string (0,any)

Country of legal entity or natural person. Required of absent in customer profile on registration!

cop string (0,any)

Confirmatino of Payee token

Request


                   
               

Response Structure

code integer (0,any)

data object

transaction string (0,any)

Token of the transaction

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

Confirmation of Payee

Endpoint

POST   /v2/cop

Operation

cop

Request Structure

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


                   
               

Response Structure

code integer (0,any)

data object

token string (0,any)

Token from operation

report object

Details of Report

match string (0,any)

Match Result

reason string (0,any)

Reason Code

name string (0,any)

Acount Owenr Name

Response


                    
                

CoP Response Codes

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

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)

Response Structure

code integer (0,any)

data object

items array[object]

amount number (0,any)

currency string (0,any)

token string (0,any)

reference string (0,any)

merchant string (0,any)

user string (0,any)

account string (0,any)

balance string (0,any)

is_instant boolean

wires object

sender_name string (0,any)

sender_iban string (0,any)

sender_bank_name string (0,any)

sender_bank_country string (0,any)

sender_bank_code string (0,any)

sender_sort_code string (0,any)

sender_account_number string (0,any)

receiver_iban string (0,any)

receiver_name string (0,any)

receiver_bank_name string (0,any)

receiver_bank_country string (0,any)

receiver_bank_code string (0,any)

receiver_sort_code string (0,any)

receiver_account_number string (0,any)

network string (0,any)

total_items integer (0,any)

Response


                    
                

Endpoint

GET   /v2/queue/{token}

Operation

queue_details

Parameters

[ token ]

Token of the queue entry

Response Structure

code integer (0,any)

data object

amount number (0,any)

currency string (0,any)

token string (0,any)

reference string (0,any)

merchant string (0,any)

user string (0,any)

account string (0,any)

balance string (0,any)

is_instant boolean

wires object

sender_name string (0,any)

sender_iban string (0,any)

sender_bank_name string (0,any)

sender_bank_country string (0,any)

sender_bank_code string (0,any)

sender_sort_code string (0,any)

sender_account_number string (0,any)

receiver_iban string (0,any)

receiver_name string (0,any)

receiver_bank_name string (0,any)

receiver_bank_country string (0,any)

receiver_bank_code string (0,any)

receiver_sort_code string (0,any)

receiver_account_number string (0,any)

network string (0,any)

Response


                    
                

Endpoint

POST   /v2/queue/{token}/process

Operation

queue_process

Parameters

[ token ]

Token of the queue entry

Response Structure

code integer (0,any)

Response


                    
                

Endpoint

DELETE   /v2/queue/{token}/return

Operation

queue_return

Parameters

[ token ]

Token of the queue entry

Request Structure

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-request

Request


                   
               

Response Structure

code integer (0,any)

Response


                    
                

Batch

Endpoint

POST   /v2/batch

Operation

batch_create

Request Structure

user_create object

email string (0,any)

first_name string (0,any)

last_name string (0,any)

dob string (0,any)

phone string (0,any)

account_create object

program string (0,any)

merchant string (0,any)

user string (0,any)

card_create object

instance string (0,any)

account string (0,any)

program string (0,any)

merchant string (0,any)

user string (0,any)

emboss_name string (0,any)

emboss_name_line4 string (0,any)

delivery_details object

city string (0,any)

country string (0,any)

zip string (0,any)

county string (0,any)

code string (0,any)

method string (0,any)

address1 string (0,any)

address2 string (0,any)

address3 string (0,any)

mobile_phone string (0,any)

pin string (0,any)

fulfil1 string (0,any)

fulfil2 string (0,any)

thermal_line1 string (0,any)

thermal_line2 string (0,any)

type string (0,any)

card_activate object

card string (0,any)

card_status object

card string (0,any)

status string (0,any)

card_renew object

card string (0,any)

mode string (0,any)

card_group_update object

card string (0,any)

group string (0,any)

group_type string (0,any)

card_assign object

card string (0,any)

merchant string (0,any)

user string (0,any)

branch_code string (0,any)

transfer object

amount number (0,any)

Amount to be deducted from customer account

currency string (0,any)

Available Options: EUR , BGN , GBP

instance string (0,any)

code 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)

debtor object

Sender of the funds

balance string (0,any)

Balance token of the customer

external_identifier string (0,any)

GPS Public token

iban string (0,any)

Valid IBAN

sort_code string (6,6)

Valid sort code

account_number string (8,8)

Valid account number

address string (0,any)

Address of legal entity or natural person. Required of absent in customer profile on registration!

name string (0,any)

Name of legal entity or natural person. Required of absent in customer profile on registration!

country string (0,any)

Country of legal entity or natural person. Required of absent in customer profile on registration!

creditor object

Receiver of the funds

balance string (0,any)

Balance token of the customer

external_identifier string (0,any)

GPS Public token

iban string (0,any)

Valid IBAN

sort_code string (6,6)

Valid sort code

account_number string (8,8)

Valid account number

address string (0,any)

Address of legal entity or natural person. Required of absent in customer profile on registration!

name string (0,any)

Name of legal entity or natural person. Required of absent in customer profile on registration!

country string (0,any)

Country of legal entity or natural person. Required of absent in customer profile on registration!

cop string (0,any)

Confirmatino of Payee token

Request


                   
               

Response Structure

code integer (0,any)

data object

token string (0,any)

Token from operation

Response


                    
                

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.

Instructions

1. Download Postman

You can download and install Postman on all operating systems from https://www.postman.com/downloads/

2. Download Paynetics API Postman Collection

Click here

3. Import Postman Collection

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.

import

import

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

import

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.

import

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.

import

  • 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.