# PaynetEasy Documentation (full)
## Integration Documentation
### General Introduction
#### Payment Gateway overview
“Payneteasy Payment Gateway” (here and hereafter System, Payment Gateway or Payneteasy) is a PCI DSS certified platform, which provides accepting, processing, storage and transmitting of payment data between participants of payment processes.
Main participants:
| Payers or Receivers | end customers of merchants. |
|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------|
| Connecting Party | merchants themselves, PSP/Payment institutions which represent merchants, or third-party systems for data exchange (CRM, BI, monitoring). |
| Processors | integrated external payment institutions and payment providers. |
Payment Gateway provides the following methods of accepting payment data:
1. API available on the Internet
2. POS-terminals
3. Virtual terminal for manual entry of payment data, received by e-mail and phone
Payment Gateway provides access to user accounts. It has the following user roles. Each root entity, can have its own Employees who can get access to the data from the root entity, but with certain restrictions:
| Merchant | provided to the merchant’s representatives (Connecting Party). |
|------------|--------------------------------------------------------------------|
| Reseller | provided to the agent, which engage merchants for Payment Gateway. |
| Manager | provided to the representatives of Payment Gateway. |
> **Note:** See all terms definitions in [Glossary](https://doc.payneteasy.com/integration/reference/glossary.html.md).
The Payment Gateway API is also published as a machine-readable
[OpenAPI 3.1 specification](https://doc.payneteasy.com/integration/openapi.html.html.md) — use it to explore the API
interactively in your browser, generate client SDKs, or integrate with
AI coding assistants. See the OpenAPI Specification page for details.
#### Connecting Party integration scenario
Depending on the PCI compliance and business requirements, Connecting party integrates to Payment Gateway via Server-to-Server APIs, Hosted payment form APIs or a combination of them. Each integration option is provided in [API Use-Cases](https://doc.payneteasy.com/integration/api_use_cases_index.html.md) section, and each API Use-Case provides clear instructions which [API commands](https://doc.payneteasy.com/integration/API_commands_index.html.md) to call on each stage of the payment flow and how to handle their results. All APIs are [asynchronous](https://doc.payneteasy.com/integration/general_api_usage/async_response.html.md). [Common utilities](https://doc.payneteasy.com/integration/common_utilities_index.html.md) section provides added value services which might be enabled by request. [FAQ](https://doc.payneteasy.com/integration/reference/faq.html.md) page helps to resolve common issues during Connecting Party integration.
Payneteasy support manager configures Projects with connected Endpoints and Endpoint Groups (if needed) for one or multiple merchant accounts of Connecting Party in Payment Gateway. For API integration, Connecting party receives the following data from Payneteasy. This data can be provided independently for sandbox (test) and production environment. Any additional required credentials are mentioned in relevant API Use-Cases.
Main required credentials are:
1. Endpoint IDs per currency or Endpoint Group IDs for multicurrency integration (see reference schema below).
2. Merchant login.
3. Merchant control key.
4. Integration scenario documentation.
```plantuml
title Options for multi-currency processing integration
package "Integration to Endpoint Group" {
class "layoutHelper1" #ffe6cc;line:black;line.dotted
class "Project\n currency A" #dae8fc;line:black;line.dotted
class "Project\n currency B" #dae8fc;line:black;line.dotted
class "Endpoint\n currency A" #ffe6cc;line:black;line.dotted
class "Endpoint\n currency B" #ffe6cc;line:black;line.dotted
class "Endpoint\nGroup" #ffe6cc;line:black;line.dotted
}
package "Integration to multiple Endpoints" {
class "layoutHelper2\n" #ffe6cc;line:black;line.dotted
class "Project\n currency C" #dae8fc;line:black;line.dotted
class "Project\n currency D" #dae8fc;line:black;line.dotted
class "Endpoint\n currency C" #ffe6cc;line:black;line.dotted
class "Endpoint\n currency D" #ffe6cc;line:black;line.dotted
}
class "layoutHelper3" #ffe6cc;line:black;line.dotted
class "Connecting Party\n (Merchant)" #e1d5e7;line:black;line.dotted
"Connecting Party\n (Merchant)" -left-> "Endpoint\nGroup"
"Connecting Party\n (Merchant)" -down-> "layoutHelper3"
"Connecting Party\n (Merchant)" -down-> "Endpoint\n currency C"
"Connecting Party\n (Merchant)" -down-> "Endpoint\n currency D"
"Endpoint\nGroup" -down- "Endpoint\n currency A"
"Endpoint\nGroup" -down- "Endpoint\n currency B"
"Endpoint\n currency C" -down- "Project\n currency C"
"Endpoint\n currency D" -down- "Project\n currency D"
"Endpoint\n currency A" -down- "Project\n currency A"
"Endpoint\n currency B" -down- "Project\n currency B"
"Connecting Party\n (Merchant)" -left[hidden]- "layoutHelper1"
"Connecting Party\n (Merchant)" -right[hidden]- "layoutHelper2\n"
"layoutHelper1" -[hidden]- "Endpoint\n currency A"
"layoutHelper1" -[hidden]- "Endpoint\n currency B"
"layoutHelper2\n" -[hidden]- "Endpoint\n currency C"
"layoutHelper2\n" -[hidden]- "Endpoint\n currency D"
hide members
hide circle
hide layoutHelper1
hide layoutHelper2\n
hide layoutHelper3
```
#### Connecting Party integration example
1. [Sale Form](https://doc.payneteasy.com/integration/api_use_cases/sale_form.html.md) - integrate hosted payment form processing of E-commerce sale transactions.
2. [Return transactions](https://doc.payneteasy.com/integration/api_use_cases/return_transaction.html.md) - integrate processing of refunds.
3. [Connecting Party callbacks](https://doc.payneteasy.com/integration/API_commands/merchant_callback_parameters.html.md) - receive transaction data to CRM, BI and other systems.
4. [Forms customization](https://doc.payneteasy.com/integration/reference/forms_customization.html.md) - brand hosted payment forms and provide them to Payneteasy support manager for installation.
5. Test the solution on sandbox with Payneteasy [test scenarios](https://doc.payneteasy.com/integration/general_api_usage/test_scenarios.html.md).
6. Inform Payneteasy support manager about successful finish of testing and request production credentials to start processing payments.
#### Payment Gateway Transaction Types
Transaction is the operation of money transfer between accounts. Payneteasy payment solution supports all common types of transactions associated with bank card and alternative payments. Transactions can be initiated via API-commands mentioned in corresponding Use-Cases, Virtual terminal, and other methods.
**Payments:**
sale - Sale is a type of transaction, in which Payer receives goods or services from Connecting Party in exchange for money or other assets. Sale combines the pre-authorization and capture process in one transaction (final authorization). Credit card associations require that Connecting Party submits a sale transaction request only when the order is fulfilled immediately. For example, when selling an item over the counter in a retail store.
preauth - Preauthorization (also preauth) is a transaction type in which bank blocks the specified amount in the Payer’s card account and does not allow the cardholder to use this blocked money. The block remains for a definite period of time. The Preauth transaction is requested when the Payer makes a purchase. Successful Preauth confirms the cardholder’s ability to pay, ensuring that the Payer’s credit card account is in good standing with sufficient funds to complete the purchase with capture request later.
cancel - Unlocks the funds blocked by Preauth transaction.
capture - After providing a service/product to the Payer, Connecting Party uses the existing pre-authorization and submits a capture request to initiate a transfer of previously held funds between the Payer’s credit card account and Connecting Party checking account.
reversal - Returns the specified amount to the cardholder’s account.
void - A credit card purchase that a seller cancels after it has been authorized but before it has been settled.
transfer - Master Card Money Send, Visa Money Transfer, and Deposit-to-Card transactions.
payout - Payout is a type of transaction which results in funds transfer from Connecting Party banking account to customer (receiver) banking account or digital wallet. Payout transaction in most cases is used for bank account funding.
**Dispute and Service transactions:**
fraud - Marks fraudulent transaction.
retrieval - The card issuer asks the merchant for a copy of the actual ticket of a transaction.
chargeback - A chargeback occurs when a cardholder contacts their credit card issuing bank to initiate a refund for a purchase made on their credit card.
chargeback_reversal - When applicable, the acquirer may process a second presentment for a chargebacked transaction.
prearbitration - The issuer may initiate an arbitration chargeback after the second presentment (2nd chargeback).
arbitration - If the acquirer does not accept financial responsibility for the Prearbitration transaction, he may pursue Arbitration (2nd chargeback reversal).
account_verification - Zero Dollar Value Authorization Request (CVV check).
pan_eligibility - Verification request to ensure that a cardholder’s account is eligible to receive Master Card Money Send transactions. Provides additional information for sending and receiving cards: the Interbank Card Association (ICA) code of the issuer, currency code (alpha and numeric), country code (alpha and numeric), brand acceptance code, and brand product code.
### 3DS Overview
#### Payneteasy 3DS Flow
Reference:
[EMV® 3-D Secure Protocol and Core Functions Specification](https://www.emvco.com/emv-technologies/3d-secure/)
3-D Secure is a protocol designed to be an additional security layer for online credit and debit card transactions.
3-D Secure protocol has two main versions.
1.0 – which was introduced in 2001 and is still used by some acquirers (Services based on this protocol were adopted by different card schemes giving it different names: Verified by Visa or Visa Secure used by Visa, Secure Code used by Mastercard, Protect By used by Discover, J/Secure used by JCB International, American Express Safe Key used by American Express.
2. X – which was introduced in 2016 to strengthen and supersede the version 1.0 and it was aimed at complying with the new EU authentication requirements and resolving some short-comings of the original protocol.
Despite low level message exchange differences in the essence protocol version 2. X differs from 1.0 by introducing and option for the issuer of the card to perform an automatic risk assessment based on the additional contextual data sent from the payer browser or mobile app, whereas 1.0 version always requires payer to pass an authentication challenge. Correspondingly (and according to EMVCo spec) protocol version 2. X includes Frictionless flow (gathering contextual data and performing risk assessment) and Challenge flow (passing authentication challenge). The normal Payer’s web flow which passes 3DS 2. X Authentication can be illustrated as below.
1. Payers fill out a payment form provided by Connection Party or Payment Gateway side and sends data.
> **Note:** For Transfer transactions, payment form might look as described below.
1. Contextual data is gathered and sent to the Issuer in a hidden process within the browser (Frictionless flow).
1. If Issuer finds the transaction risky Payer’s browser gets redirected to the Issuer web page to pass authentication challenge (Challenge flow).
1. When Payer passes checks the payment authorization is made saving the details related to the 3DS Authentication on the acquirer side.
1. Payer’s browser gets redirected to the Connecting Party website to the resultant page.
Due to the fact that both protocol versions still used the Connecting party have to deal with both of them as well as specific integrations when acquirer handles 3D Secure communication on its end. For this purpose, Payment Gateway provides universal/generic approach based on the API commands which allow the Connecting party to handle all mentioned cases. The Connecting Party has to start with the 3DS Decision Making Schema of the relevant Use-Case which in turn refers to the more detailed diagram describing specifics of the data handling and Payer’s browser redirects related to the corresponding 3DS flow.
#### 3DS Implementation Scenarios
| Implementation Scenario | Instructions |
|------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 3DS is not initiated (non3D). | 3DS Authentication is not initiated. Follow 3DS Decision Making Schema of relevant Use-Case and implement Non3D Flow. |
| 3DS is initiated and performed by Connecting Party (for PSPs and Acquirers). | 3DS Authentication is initiated and performed by Connecting Party, results are uploaded to Payment Gateway in initial request. Follow 3DS Decision Making Schema of relevant Use-Case and implement Non3D Flow (3DS is performed before the initial request to Payment Gateway). |
| 3DS is initiated by Payment Gateway and performed on Connecting Party side. | 3DS Authentication is initiated by Payment Gateway. For 3DS 1.0.2, Payer Authentication is performed on Connecting Party side, results are uploaded to Payment Gateway. For 3DS 2.x, 3DS Method and Challenge are performed on Connecting Party side, results are uploaded to Payment Gateway. Additional fields for 3DS Method can be provided by Connecting Party in initial request to speed up the process for 3DS 2.x (tds_status=Method Url Frame will be skipped if 3DS Method is not supported by ACS). Follow 3DS Decision Making Schema of relevant Use-Case and implement all 3DS Flows. |
| 3DS is initiated and performed by Payment Gateway. | 3DS Authentication is initiated by Payment Gateway, all 3DS scenarios are performed on Payment Gateway side. Follow 3DS Decision Making Schema of relevant Use-Case, implement Simplified Authentication Flow (ignore tds_status parameter presence, use html or redirect-to parameters to redirect the Payer to Payment Gateway) and Non3D Flow (if Payer’s card is not enrolled or processing is Non3D). |
#### 3DS Decision Making Schema
```plantuml
@startuml
title 3DS Decision Making Schema
start
: (1) Send **/api/v2/status** request\nwith orderid=**paynet-order-id**\nProcess **/api/v2/status** response;
while ((2) Check If **status** response field equals\nto finished status values\n**status** == approved\nOR **status** == declined\nOR **status** == error\nOR **status** == unknown\nOR **status** == filtered) is (NO);
if ((3) **tds_status** field is present) then (YES)
if ((4) **tds_status** == MethodUrlFrame?) then (YES)
#Plum :(5) Create iframe\nto pass 3DS Method\n3DS 2.x Frictionless flow\nto be applied.\n\nSee 3DS 2.x Frictionless Flow;
(NO ) elseif ((6) **tds_status** == CReqForm?) then (YES)
#Plum :(7) Create CReq HTML Page\nwhich redirects to ACS\n3DS 2.x Challenge Flow\nto be applied\n\nSee 3DS 2.X Challenge Flow;
(NO ) elseif ((8) **tds_status** == PaReqForm?) then (YES)
#Plum :(9) Create PaReq HTML Page\nwhich redirects to ACS\n3DS 1.0.2 Authentication Flow\nto be applied\n\nSee 3DS 1.0.2 Authentication Flow;
endif
(NO )elseif ((10) **html** field is present) then (YES)
#Plum :(11) Return content of the\n**html** field to the Payeras is \n(3DS 2.x or 1.0.2 to be applied)\n\nSee Simplified authentication flow;
else (NO)
endif
backward:(12) Send new\n**/api/v2/status** request\nProcess\n**/api/v2/status** response;
endwhile (YES)
:(13) Show result page to the Payer;
stop
legend left
=Legend
| Color | Implementation responsibility |
|<#Turquoise>| Connecting party |
|<#Plum>| Connecting and other party |
| | Other Party |
endlegend
@enduml
```
Connecting party has to implement all steps marked in green and purple. Below are the description for steps which reference specific API commands according to the step ID:
(1) To implement order status request see [/api/v2/status/](https://doc.payneteasy.com/integration/API_commands/api_v2_status.html.md). Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.
(5) If tds_status is Method Url Frame see [Frictionless 3DS 2.x](#ds-2x-frictionless-flow-overview).
(7) If tds_status is CReq Form see [3DS 2. X Challenge](#ds-2x-challenge-flow-overview).
(9) If tds_status is Pa Req Form see [3DS 1.0.2 Authentication](#ds-102-authentication-flow-overview).
(11) If tds status is not present, but html field is present, see [Simplified authentication](#simplified-authentication-flow-overview).
(12) The same as point (1).
##### Non3D Flow
Transaction should be considered as non3D (no 3DS authentication) if all conditions are met:
1. steps 1-2-(12)-13 of [3DS decision making schema](#ds-decision-making-scheme-overview) were followed.
2. tds_status, html and redirect-to parameters were not present.
3. transaction received final status (approved, declined, error, filtered).
> **Note:** Please note that transaction status “unknown” might appear for both 3DS and non3D transactions. See details in [Statuses](https://doc.payneteasy.com/integration/API_commands/api_v2_status.html.md).
##### 3DS 2.x.0 Frictionless Flow
```plantuml
title 3DS 2.x.0 Frictionless Flow
start
#Turquoise:(1) Send **/api/v2/status/** API request;
#Turquoise:(2) Process **/api/v2/status/** response.
Gather:
**tds-method-url-frame-3ds-server-trans-id**
**tds-method-url-frame-3ds-method-url**;
if ((3) **tds-method-url-frame-3ds-method-url** is present) then (yes)
#Turquoise:(4) The Connecting Party constructs **3DS Method HTML Page**\ncontaining hidden iframe and upload **3DS Method Result HTML Form**\nusing the parameters received on the previous steps\nand providing **threeDSMethodNotificationURL**;
#Turquoise:(5) HTML Page, once rendered, is automatically submitted
into iframe (using HTML Page target attribute);
fork
note left
**iframe** lifecycle
end note
:(6) Payer's iframe gets redirected to
**tds-method-url-frame-3ds-method-url**
URL (Issuer ACS);
:(7) Issuer ACS collects Payer Identity Data from browser;
:(8) Issuer ACS notifies (using HTTP POST)
**threeDSMethodNotificationURL** on completion;
#Turquoise:(9) When notification is received gather **threeDSMethodData**.
Base64Decode it and check **threeDSServerTransID**;
#Turquoise:(10) Save **threeDSCompInd=Y** for the current Transaction;
#Turquoise:(11) Return **3DS Method Done HTML Page**;
fork again
note left
**3DS Method HTML Page** lifecycle
end note
repeat
#Turquoise:(12) Check if Issuer ACS notification
is received from iframe internal JavaScript;
repeat while ((13) notification is recieved OR timeout exceeded?) is (no)
-> (yes);
if ((14) timeout exceeded?) then (yes)
#Turquoise:(15) Save **threeDSCompInd=N**
for the current Transaction;
else (no)
endif
:(16) After executing 3ds method\nsend data to connecting party's server;
end fork
else (no)
#Turquoise:(17) Save **threeDSCompInd=U**
for the current Transaction;
endif
#Turquoise:(18) Send **api/3ds/v1/upload-method-url-result/** request
with the collected Payer's data and **threeDSCompInd**,
Payer's browser info and **notificationURL**
which is to be used further in the Challenge Flow
(see 3DS Decision Making Schema and 3DS 2.X Challenge Flow).;
#Turquoise:(19) Send **/api/v2/status/** API request
Process **/api/v2/status/** response and follow **3DS Decision Making Schema**.;
stop
legend left
=Legend
| Color | Implementation responsibility |
|<#Turquoise>| Connecting party |
| | Other Party |
endlegend
```
Connecting party has to implement all steps marked in green. Below are the description for steps which reference specific API commands according to the step ID:
(1) To implement order status request see [/api/v2/status/](https://doc.payneteasy.com/integration/API_commands/api_v2_status.html.md). Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.
(2) The same as point (1).
(4) To construct 3DS Method HTML page see [example](#frictionless-3ds-method-html-page-overview) below.
(9) To process 3DS Method Notification see [Process 3DS Method Notification](#frictionless-3ds-method-process-3ds-overview).
(11) To construct 3DS Method Done HTML page see [example](#frictionless-3ds-method-done-html-page-overview).
(18) To upload method url result see [/api/3ds/v1/upload-method-url-result/](https://doc.payneteasy.com/integration/API_commands/upload-method-url-result.html.md).
(19) The same as point (1).
###### 3DS Method HTML Page Example
3DS Method HTML Page example below performs 3DS Method initiation through iframe technique and holding of the Payer’s browser until the 3DS Method is not finished on the Connecting Party server. Once it is finished or timeout is reached Connecting Party has to follow the next steps following 3DS Decision Making Schema and redirect Payer’s browser to the corresponding URL (either Challenge Flow or payment result page). Normal timeout value is 30 sec.
3DS Method HTML Page consists of the following parameters:
| Parameter | Description |
|-------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| tds-method-url-frame-3ds-method-url | ACS 3DS Method URL is received by the Connecting Party in the [/api/v2/status/](https://doc.payneteasy.com/integration/API_commands/api_v2_status.html.md) response. |
| tds Method Upload Url | Connecting Party’s URL, where the result comes after the completion of the flow. |
| threeDSMethod Data | JSON value containing threeDSServer TransID and threeDSMethod NotificationURL. See below how to [construct threeDSMethod Data](#frictionless-3ds-method-html-page-threedsmethoddata-overview). |
**Construct threeDSMethod Data**
In order to **construct threeDSMethod Data** the Connecting Party has to use the following parameters.
| Parameter | Description |
|------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| threeDSServer TransID | Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction. Received in the [/api/v2/status/](https://doc.payneteasy.com/integration/API_commands/api_v2_status.html.md) response as tds-method-url-frame-3ds-server-trans-id parameter. |
| threeDSMethod NotificationURL | The URL that will receive the notification of 3DS Method completion from the ACS. The Connecting Party is responsible for providing valid threeDSMethod NotificationURL. Normally when the Connecting Party receives any request on this URL is has to return 3DS Method Done HTML Page (see [example](#frictionless-3ds-method-done-html-page-overview) below). |
**threeDSMethod Data construction example**
1. **Construct threeDSMethod Data** JSON.
```http
{"threeDSServerTransID":"3d671629-a410-4a5d-9288-b38ceadd41f2","threeDSMethodNotificationURL":"https://connectingparty.com/3ds-method-complete/"}
```
1. Apply base64 url encoding to resultant JSON.
```http
eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNkNjcxNjI5LWE0MTAtNGE1ZC05Mjg4LWIzOGNlYWRkNDFmMiIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJodHRwczovL21lcmNoYW50LmNvbS8zZHMtbWV0aG9kLWNvbXBsZXRlLyJ9
```
**Generate Fingerprint**
The 3DS Method can be optionally used by issuers to gather browser fingerprints using Java Script. This is done by loading a URL in a hidden iframe, before the authentication. This iframe will then execute some fingerprinting Java Script, before POST’ing to the prespecified URL belonging to the requestor. The 3DS Method fingerprint result is tied to the authentication by the threeDSServer TransID.
```js
function gatherBrowserData() {
var colorDepth = screen.colorDepth; // 24
var javaEnabled = navigator.javaEnabled(); // true
var browserLanguage = navigator.language; // en_US
var screenHeight = screen.height; // 1080
var screenWidth = screen.width; // 1920
var userAgent = navigator.userAgent; // Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.110 Safari/537.36
var browserTimezoneZoneOffset = new Date().getTimezoneOffset(); // 0
}
```
**Construct 3DS Method HTML page example**:
```html
ACS v2 3DS Method ...
```
###### Process 3DS Method Notification
When 3DS Method is completed, the Connecting Party receives HTTP POST request at threeDSMethod NotificationURL with threeDSMethod Data, which contains threeDSServer TransID (in base64 encoded JSON).
1. Get threeDSMethod Data.
```js
threeDSMethodData=eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNkNjcxNjI5LWE0MTAtNGE1ZC05Mjg4LWIzOGNlYWRkNDFmMiJ9Cg
```
1. Apply base64 url decoding to get JSON, which contains threeDSServer TransID.
```json
{"threeDSServerTransID":"3d671629-a410-4a5d-9288-b38ceadd41f2"}
```
###### 3DS Method Done HTML Page Example
```html
ACS v2 3DS Method Notification Handler...
This should not be displayed
```
##### 3DS 2.x.0 Challenge Flow
```plantuml
title 3DS 2.x.0 Challenge Flow
start
#Turquoise:(1) Send **/api/v2/status/** API request;
#Turquoise:(2) Process **/api/v2/status/** response.
Gather:
**tds-creq-form-creq**
**tds-creq-form-acs-url**;
#Turquoise:(3) Construct CReq HTML Page based on the gathered parameters.
Add **threeDSSessionData** with the custom data
in the format: Max length: 1024 bytes, format: Alphanumeric,
base64url encoded without padding.;
#Turquoise:(4) Return CReq HTML Page to Payer's browser;
:(5) CReq Page gets redirected to ACS URL **tds-creq-form-acs-url**.
Payer passes 3DS Challenge Verification.
ACS return CRes Page.
CRes Page gets submitted to **notificationURL**;
#Turquoise:(6) Process CRes Page parameters.
Gather parameters:
**cres**
**threeDSSessionData**;
#Turquoise:(7) Send HTTP POST **/api/3ds/v1/upload-cres-result/** API Request
providing **cres**, **orderid=paynet-order-id**;
#Turquoise:(8) Send **/api/v2/status/** API request
Process **/api/v2/status/** response and follow **3DS Decision Making Schema**.;
stop
legend left
=Legend
| Color | Implementation responsibility |
|<#Turquoise>| Connecting party |
| | Other Party |
endlegend
```
(1) To implement order status request see [/api/v2/status/](https://doc.payneteasy.com/integration/API_commands/api_v2_status.html.md). Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.
(2) The same as point (1).
(3) To create CReq HTML Page see [example](#creqform-example-overview).
(5) To implement CRes redirect see [CRes redirect](https://doc.payneteasy.com/integration/API_commands/CRes_redirect.html.md).
(7) To upload CRes result see [/api/3ds/v1/upload-cres-result/](https://doc.payneteasy.com/integration/API_commands/upload-cres-result.html.md).
(8) The same as point (1).
###### CReq HTML Page Example
CReq HTML Page redirects the Payer’s browser to ACS Server URL, provided in tds-creq-form-acs-url parameter. The result CRes value will be returned from ACS to notificationURL provided by Connecting Party in [/api/3ds/v1/upload-method-url-result](https://doc.payneteasy.com/integration/API_commands/upload-method-url-result.html.md) request during 3DS 2.x.0 Frictionless Flow.
| Field | Description | Necessity |
|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|
| creq | ACS 3DS CReq data, which received by the Connecting Party in the [/api/v2/status/](https://doc.payneteasy.com/integration/API_commands/api_v2_status.html.md) response. The same as tds-creq-form-creq. | Required |
| threeDSSession Data | value which will be posted back within CRes to notificationURL at the end of the process. Max length: 1024 bytes, format: Alphanumeric, Base64url encoded without padding. | Optional |
```html
Redirecting ...
```
##### 3DS 1.0.2 Authentication Flow
```plantuml
title 3DS 1.0.2 Authentication Flow
start
#Turquoise:(1) Send **/api/v2/status/** API request;
#Turquoise:(2) Process **/api/v2/status/** response.
Gather:
**tds-pareq-form-pareq**
**tds-pareq-form-acs-url**;
#Turquoise:(3) Construct PAReq HTML Page based on the gathered parameters.
Add **TermUrl** where the Payer gets redirected back with PARes data submitted.
Add **MD** with the custom data which is be posted back.;
#Turquoise:(4) Return PAReq HTML Page to Payer's browser;
:(5) PaReq Page gets redirected to ACS URL **tds-pareq-form-acs-url**;
:(6) Payer passes 3DS Challenge Verification;
:(7) ACS returns PARes Page;
:(8) PaRes Page gets submitted to the **TermUrl**;
#Turquoise:(9) Process PARes Page parameters.
Gather parameters:
**PaRes**
**MD**;
#Turquoise:(10) Send HTTP POST **/api/3ds/v1/upload-pares-result/** API Request
providing **paRes**, **orderid=paynet-order-id**;
#Turquoise:(11) Send **/api/v2/status/** API request
Process **/api/v2/status/** response and follow **3DS Decision Making Schema**.;
stop
legend left
=Legend
| Color | Implementation responsibility |
|<#Turquoise>| Connecting party |
| | Other Party |
endlegend
```
(1) To implement order status request see [/api/v2/status/](https://doc.payneteasy.com/integration/API_commands/api_v2_status.html.md). Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.
(2) The same as point (1).
(3) To construct Pa Req HTML Page see [example](#pareqform-example-overview).
(5) To implement Pa Res redirect see [Pa Res redirect](https://doc.payneteasy.com/integration/API_commands/Pa Res_redirect.html.md).
(10) To upload Pa Res result see [/api/3ds/v1/upload-pares-result/](https://doc.payneteasy.com/integration/API_commands/upload-pares-result.html.md).
(11) The same as point (10).
###### Pa Req HTML Page Example
Pa Req HTML Page redirects the Payer’s browser to ACS Server URL, provided in tds-pareq-form-acs-url parameter.
Pa Req HTML Page consists of the following parameters:
| Field | Description | Necessity |
|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|
| tds-pareq-form-acs-url | ACS 3DS Pa Req URL is received by the Connecting Party in the [/api/v2/status/](https://doc.payneteasy.com/integration/API_commands/api_v2_status.html.md) response. | Required |
| MD | Connecting Party Data, which comes back to your termination page. | Optional |
| Pa Req | ACS 3DS Pa Req data, which received by the Connecting Party in the [/api/v2/status/](https://doc.payneteasy.com/integration/API_commands/api_v2_status.html.md) response. The same as tds-pareq-form-pareq. | Required |
| TermURL | URL of termination page, where the Payer gets redirected back with Pa Res data submitted. | Required |
```html
Loading acs..
```
##### Simplified Authentication Flow
```plantuml
title Simplified Authentication Flow
start
#Turquoise:(1) Send **/api/v2/status/** API request;
#Turquoise:(2) Process **/api/v2/status/** response;
fork
#Turquoise:(3)Gather **html** parameter;
#Turquoise:(4) Return content from **html** parameter to the Payer's browser as is;
forkagain
#Turquoise:(5)Gather **redirect-to** parameter;
#Turquoise:(6)Redirect Payer to redirect URL (value of redirect-to parameter);
endfork
:(7) Payer's browser gets redirected to ACS and Payer passes either 3DS 1.0.2 or 3DS 2.X flow.;
:(8) Payer's browser gets redirected back to **redirect_url** provided in the initial **api/v2/sale/** request.;
#Turquoise:(9) Process Payer's Browser final redirect to **redirect_url**.;
#Turquoise:(10) Return Wait HTML Page to the Payer's browser;
fork
note left
**Wait HTML Page** lifecycle
end note
repeat
#Turquoise: (11) Request Connecting Party Server on the status of the transaction;
#Turquoise: (12) Process transaction status;
repeat while ((13) Received finished status\n(approved, declined, error, filtered or unknown)?) is (no)
-> (yes);
#Turquoise:(14) Redirect Payer's browser to the result page;
fork again
note left
**Connecting Party Server** lifecycle
end note
repeat
#Turquoise:(15) Send **/api/v2/status/** API request;
#Turquoise:(16) Process **/api/v2/status/** response;
repeat while ((17) Received final status from "Payneteasy") is (no)
-> (yes);
#Turquoise:(18) Save transaction status;
end fork
stop
legend left
=Legend
| Color | Implementation responsibility |
|<#Turquoise>| Connecting party |
| | Other Party |
endlegend
```
(1) To implement order status request see [/api/v2/status/](https://doc.payneteasy.com/integration/API_commands/api_v2_status.html.md). Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.
(2) The same as point (1).
(6) To implement final redirect see [Final redirect](https://doc.payneteasy.com/integration/API_commands/final_redirect.html.md).
(7) The HTML wait page on Connecting Party side can have custom design and should communicate with Connecting Party server as described on the diagram.
(12) and (13) The same as point (1).
#### Alternative cardholder authentication
Payment Gateway supports alternative methods for cardholder authentication if card is not enrolled to 3DS (negative 3DS enrollment response). One of such methods is random sum check. In this method, Payment Gateway initiates an additional preauthorization transaction to hold a random small amount on cardholder’s account and sends a special form for the Payer to enter the amount being held. If the amount is correct, Payment Gateway continues to process the initial transaction. The small amount hold is cancelled automatically.
##### General diagram for form transactions
```plantuml
skinparam roundcorner 20
skinparam sequenceArrowThickness 2
skinparam ParticipantPadding 30
actor Payer as Customer
participant "Connecting Party" as Merchant
participant "Payment Gateway" as g
autonumber
Customer -> Merchant: Checkout
activate Merchant
== Purchase payment request ==
Merchant -> g: Request Initiating
activate g
g --> Merchant: Redirect-url, Order ID
deactivate g
Merchant -> Customer: Provide redirect-url to Payer's browser
activate Customer
Customer -> g: GET redirect-url
deactivate Customer
activate g
g -> Customer: Payment Form
deactivate g
activate Customer
Customer -> g: Submit Form
deactivate Customer
activate g
g -> g: Transaction processing
g -> g: 3DS Enrollment
g -> g: Random Sum Processing
g -> Customer: Redirecting to the Random Sum Check html form
deactivate g
activate Customer
Customer -> g: The cardholder provides auth data
deactivate Customer
activate g
g -> g: Auth Data Validating
group alt
== Receive Connecting Party Callback ==
Merchant <- g: Сallback with final status
g <-- Merchant: HTTP 200
deactivate g
== Order Status Request ==
Merchant -> g: api/v2/status
activate g
g --> Merchant: Response \nstatus, order-stage
deactivate g
end
Merchant --> Customer: Show result
deactivate Merchant
deactivate Customer
```
(2) See relevant Use-Case to get details about the exact API command to initiate transaction.
(13) To implement callback with final status handling see [Connecting Party Callbacks](https://doc.payneteasy.com/integration/API_commands/merchant_callback_parameters.html.md).
(15) Please see [Status List](https://doc.payneteasy.com/integration/statuses.html.md) to get more information about Final Statuses.
##### General diagram for direct integrations
```plantuml
skinparam roundcorner 20
skinparam sequenceArrowThickness 1
skinparam maxmessagesize 1200
skinparam sequenceParticipant underline
actor Payer
participant "Connecting Party" as A
participant "Payment Gateway" as B
autonumber
Payer -> A: Checkout
activate A
A -> B: Payment Initiating
activate B
B --> A: Order ID
B -> B: Transaction processing
group loop
A -> B: Status Request
B --> A: Non-Final Status
end
B -> B: 3DS Enrollment
B -> B: Random Sum Processing
A -> B: Status Request
B -> A: Response with Random Sum Check html form
A -> Payer: Redirecting to the Random Sum Check html form
deactivate B
activate Payer
Payer -> B: Cardholder provides auth data
deactivate Payer
activate B
B -> B: Auth Data Validating
group alt
group Get Final Status
== Receive Connecting Party Callback ==
A <- B: Callback with Final Status
A --> B: HTTP 200
deactivate B
== Order Status Request ==
A -> B: Get Status by Order ID
activate B
B --> A: Response status, \norder-stage
deactivate B
end
A --> Payer: Show result
deactivate A
```
(2) See relevant Use-Case to get details about the exact API command to initiate transaction.
(9) Status Request continues in parallel all the time starting from step 5.
(11) To implement callback with final status handling see [Connecting Party Callbacks](https://doc.payneteasy.com/integration/API_commands/merchant_callback_parameters.html.md).
(13) Please see [Status List](https://doc.payneteasy.com/integration/statuses.html.md) to get more information about Final Statuses.
### API Commands, Callbacks & Redirects
### CRes Redirect
#### CRes Redirect Parameters
CRes redirect to connecting party’s website is performed when a payer ends Challenge flow. Final redirect is initiated from within payers browser using HTTP POST method.
HTTP payload contains CRes parameters which in turn contains base64 encoded json (see example below).
| Redirect parameter name | Description |
|---------------------------|-------------------------------------------------------------------------------------|
| serial-number | Unique number assigned by Payneteasy server to particular request from the Merchant |
| merchant-order-id | Merchant order id |
| paynet-order-id | Order id assigned to the order by gate.payneteasy.eu |
#### Redirect Request Example
Connecting party receives HTTP POST request base64 encoded **CRes** parameter similar to below:
```http
cres=ewogICJtZXNzYWdlVHlwZSIgICAgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCgogICJ0aHJlZURTU2VydmVyVHJhbnNJRCIgOiAic29tZVRocmVlRFNTZXJ2ZXJUcmFuc0lEIiwKICAiYWNzVHJhbnNJRCIgICAgICAgICAgIDogInNvbWVBY3NUcmFuc0lEIiwKCiAgImNoYWxsZW5nZUNvbXBsZXRpb25JbmQiIDogIlkiLAogICJ0cmFuc1N0YXR1cyIgICAgICAgICAgICA6ICJZIgp9
```
After decoding cres one will find a json similar to below:
```json
{
"messageType" : "CRes",
"messageVersion" : "2.1.0",
"threeDSServerTransID" : "someThreeDSServerTransID",
"acsTransID" : "someAcsTransID",
"challengeCompletionInd" : "Y",
"transStatus" : "Y"
}
```
### Pa Res Redirect
#### Pa Res Redirect Parameters
Pa Res redirect to connecting party’s website is performed when a payer ends 1.0.2 authentication flow.
Final redirect is initiated from within payers browser using HTTP POST method.
HTTP payload contains Pa Res parameters which in turn contains base64 encoded json (see example below).
| Redirect parameter name | Description |
|---------------------------|-------------------------------------------------------------------------------------|
| serial-number | Unique number assigned by Payneteasy server to particular request from the Merchant |
| merchant-order-id | Merchant order id |
| paynet-order-id | Order id assigned to the order by gate.payneteasy.eu |
#### Redirect Request Example
Connecting party receives HTTP POST request deflate archived base64 encoded Pa Res parameter similar to below:
```http
paRes=eJydlluTokgThu/nVxhOxN4YPZwV5rPdKI6CgHIQxTsaEDnIWUB//aL09Ngdc7HfcgFFkvnwZmVWRc3/7s7JqPHLKszS1zHyAx6P/NTNvDANXsdbk38hx6OqdlLPSbLUfx2n2fjvxdw8lb7PGr57Kf3Ft9FoNFf8qnICfxR6r2P4/Xr5dUM+Rv01JY6edxw/wu6RG6D71f8fdw99173oZf9A59Cv1ycPxS/dk5PWT7a72XELWlQXOIJMCXIOvb9+9jn7pcguEBTDiemMpOA5NFie6NAf8PPN5W6r/C+4LvQWamTjKstdVZhRuPwk8vvOkKPDbt2A1zl09/gc4zm1v0BhFEFgdDaC0Z8I/BPvE33YP7v2lSj7wl0XUxybQx9vn538Lu+L2MvtGR/jzy75XT04Z5f+C3Kf9jn0bHpO/g+JznMnXcxQjIBRlJgRBIGi6Gw6JQmSmvU2pJ/ru8dTgLn/IqAOz59zxqmfBDGHHvbPrn1f1pdqYc+h99GXbN1wAfeR9+ez7t+/7HO4N9/QwUYYpD2l9Ef9kkir1/GprvOfENS27Y8W+5GVAYT28wHBFNQ7eFUYfB8vHlG+J6bHbDFnnDRLQ9dJwptT942o+PUp80YgCbIyrE/nPyFN/U5FIJ1jXnrsi4vg6cvdAmMIMYYWv2X9G9pXgWXlvFQnB7mDdP/o35vCH2118XX8/d+ttjkbBn5V/5ef//rxQLCc5OIvVLFd0tZGl5PaWkMNtmqIDYDqdQnh/Qp49pxDH4L78fM0f8zI4ChXgtEZhyIt0K6WdJy5vhUC2dnwKScKue1cfDNt8ZlKzFaheInrfQNtd44xWZaSiTh2q+mWZ6gTqN0I7F/fEex/31QZhlr2sgOIutoh2tlvOKiBsCyuaDTx1ifdz72tLNgXrcJ8xvBpouWza+G0+DJwILpyCkrN+Qll5idnIIoYvK3WmLDCzukJmxWQkjmkncm0S7jN7AbsSA9xDGwm1ZbxogMeHwywYgpR32FwNUHla0rGF5ZChN2qGIjsmfYPqJQIlGKqWcLoYMXVuupPJrk+ESZhh+5YCIrVYi1NCDoPpWXrOuky80TBzLRbmsxcoKAcRs6C/UAs5KVhozuIn/oB7iH224yPfBviFW7Ke911RebqRQleX4diPBVgvvKvQ2X2BEyxTu0MI8Yv6/DYr4d+s1JEkd2yDAOigGE05mY62yk6YW+HG1DpIC5OcShQLUwDreIBSxeKVrWMZrOWpglcK9k7lpMVEAsA2XKDXAa0zI4POs4EGzpQLRq4CsPriYvpkbPXCUXXWi54EFYsqLeHvQprKFW7An/xTU5XAPmgMW0rDkRLsG4eb12cvdZxEdAGqqIw1oNK25jSKibw+Ra+9k9CYeNOMblbXwDnYYt+2wbi/YsiZB1zA9JAs02QnOyn7EQWPLL70EP3eh5KBDX3lnHHs8C4xw5EGmQKgzz0sG8o0to7os+Ua9n2QZNZcHpkau2I3GM5Q6HBgwraVnpQOT5yb6Dr60G/t2b0tQIcD8CaARoJ7l5MsOrHHECQws5DYVJaBy5MOjzbe3GL+JjH0NaK4Fy53xoGorGKpfqYi2wDgSu8v8UJFC831Zt8pRhCQmK3K0wYz3QxMLeacHEsam0Gld1SwnIWQKR6EN84ZT2N6F2yG4gJqabAXreFaDh2pcrbyJZo/GAdaCWIeaXgSpFgGdN0Qbd+Q69YZbilJEWWVfjTc3EKOXrvULeio4woHojt4TpDqBPxpsrTmshXpLnd8Yl7zWaYpdRtgFsk1pDAMugusQBIrJp3G9DYcllPrh2JGLGVLtE9pl4kZiCetLXfyDY8WW4beD/btHbphr2inYQRgqhY0Cw/LI03wfCCIxxCFdvcWKEHZJ2A7+ibdlsXtIGtnOzW5QMRa/vm0ACtAFhgjEIwxDeM1TiaabcA4GJfKZpIG87BcaqY6da6ZByDu1x1WyHI2yTh4BsxwQz5LYowfiBGhcupZ4/zk9UVeGQLKzB3nZS7xGFX2rrOupaLkq00QSZr0loiql4yjeBsjpJtxlvnyGIrfyn1fYutdu8dnjNxkqCqvAq3pmDlR+QApwpWoUZsg6iaIC61OU6yvTpLwgt0FVW2wVXytJajOF+SmL3ZSxRqvWktdbm+d3hE+RtJ2/gGdswlzoeJGK0tqk21NaVFbkfthLUCkfLyIBy8oyi1K2epL/GqPbrttVQamLLcDWSk28Su39d1UyRkgxZ2sybgTC+9DK4PRiNLOyKZGmZ18qMqv+jQ8lozEKVHDELWuJpSvHWeuSzC9eekmaqJq3oOfd3VBsuw40Efu+Dv/XFxPyE+zsWLb/254/nQ/A8pzm2f
```
After decoding pa Res one will find a xml similar to below:
```xml
1.0.24116581234567890NjY4NDEyN0CMEphIFXxSLjZWOvA=20211027 02:10:426432100007235022575552227668589750218Y05NIwHBVPRLltVO/v3Kv5PA/tOr/4=LsGSxSZqnq2xtJR4CybqG8xY0hp5qLwxc4P6w47N57KiIuktXv/UWaS+HrJT1aYwQRVdSN+/wPGD
NL0/wDuWA1NKW1QmevE/v/3oksB2ldOhRepdULGYuQs3eCSeB5wFoyqaw4Hga/Bsaq9NpF+9Tpha
I30UsO3GK3mnh37q/Moa8YoLBc5cv7zAYjRi43AP+sUCdjZ4kZSAKCqIRW30s+2Lyn8kuD91GWKq
DmBeZ2JlG9MTNolCRAKEtRNe++pR+G+ix2WD//kNqOJ+5BpiJHwcanHodIGToQznl7cAM2E387gX
qLHSY2W/F6eg4d1Yb7FjeY/FME6FdxyK8pNuMg==MIIDUDCCAjgCCQCzTaU62+DzZzANBgkqhkiG9w0BAQsFADBqMQswCQYDVQQGEwJYWDELMAkGA1UE
CAwCWFgxETAPBgNVBAcMCFRlc3RjaXR5MRQwEgYDVQQKDAtUZXN0Q29tcGFueTERMA8GA1UECwwI
VGVzdFVuaXQxEjAQBgNVBAMMCVRlc3RBY3MwMTAeFw0yMTA5MDkxMTEzMTNaFw0yMjA5MDkxMTEz
MTNaMGoxCzAJBgNVBAYTAlhYMQswCQYDVQQIDAJYWDERMA8GA1UEBwwIVGVzdGNpdHkxFDASBgNV
BAoMC1Rlc3RDb21wYW55MREwDwYDVQQLDAhUZXN0VW5pdDESMBAGA1UEAwwJVGVzdEFjczAxMIIB
IjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA11qYpiG+rVZEilx4oXdkw1e3dCBVK5EcLlgo
SKkJtfpIDv/Ay0Xzkl/kHPsbLy9C5J1kcxqT04oRIgTUQGuaV9OTgsYw9GH7g/8NZIbEMO6jBWlW
l8NnAYOwqISaYsNLUjYJB4ZVZBMgkFMqErI5DCTTcAxOb2y3sScrJJjVVqe6mqhiEBXa9zqx9Sjk
wZy719h5bNL6t5pK8TUWFlcyo73VMtwg4V83v8AVSBxlVAAlVtFcvAvYLrt+yx81SkVnH2X3NuJC
hQOevLY0+HUv0X7PwYrciTcAWJ35GIMV/7pZHSbGSdgf0i/sDvzDGX3NoxG4WBzQzOqBS3Kaozxp
3wIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQB5nvEa449q7RVOrCaSEuyRYM58z+lE0z5+3SLbjj3F
jqcENmdEelKyAd8w0M0Ey+rWlaDKQOtoxwEjlUJ+1+O8VH1NRrCvGaPfJYTkUafD3KeHJQYD3KWz
pCkll2NLKiUTGVpf1Z0nM3s2SkYAjs+1c9Pf+oXN7liu/yINDv4N8hOLjkpH83YPXJ92VbQw9uyV
j9ePJQPeS3fpJEe05k2tV9wnQO9Qjcx9WGOM/8LHZGZdfIJwKaHRH4swfcwyrMv09VcP/SnUlYtI
vql8v2qYvO50oRrdo0tZSvLJW5l6STshejspuR/HytC/9RjC18t4Nn9FVm7cD1Expo7NQIKt
```
### Account Verification Form
#### Introduction
Account verification is a non-financial transaction, which allows to validate Payer’s card account information. This verification procedure helps to prevent potential fraudulent activity and meet industry-specific compliance obligations. Account Verification Form integration allows Connecting Party to exclude itself from storing, processing, or transmitting Payer’s cardholder data or other sensitive payment details. Such data is submitted by Payer on Payneteasy hosted payment form in PCI DSS certified environment.
See terms definitions in [Glossary](https://doc.payneteasy.com/integration/reference/glossary.html.md).
#### Account Verification Form Flow
```plantuml
skinparam roundcorner 20
skinparam sequenceArrowThickness 2
skinparam ParticipantPadding 30
actor Payer as Customer
participant "Connecting Party\nwebsite" as Merchant
participant "Payment Gateway" as g
autonumber
Customer -> Merchant: Checkout
activate Merchant
== Account Verification Request ==
Merchant -> g: api/v2/account-verification-form
activate g
g --> Merchant: Redirect-url, orderId
deactivate g
Merchant -> Customer: Provide redirect-url \nto payer’s browser
deactivate Merchant
activate Customer
Customer -> g: GET redirect-url
deactivate Customer
activate g
g --> Customer: Account Verification Form
deactivate g
activate Customer
Customer -> g: Submit form
deactivate Customer
activate g
g --> g: Process Account Vetification transaction
== Final redirect of customer ==
g -> Customer: Redirect to Connecting Party website
activate Customer
Customer -> Merchant: POST redirect_url\nstatus, orderid
deactivate Customer
activate Merchant
group Get Final Status
== Receive Connecting Party Callback ==
Merchant <- g: Сallback with final status
g <-- Merchant: HTTP 200
deactivate g
== Order Status Request ==
Merchant -> g: api/v2/status
activate g
g --> Merchant: Response \nstatus, order-stage
deactivate g
end
Merchant --> Customer: Show result
deactivate Merchant
```
(2) To implement Account Verification Form request see [/api/v2/account-verification-form/](https://doc.payneteasy.com/integration/API_commands/api_v2_account-verification-form.html.md).
(9) To implement final redirect see [Final Redirect](https://doc.payneteasy.com/integration/API_commands/final_redirect.html.md).
(11,12) To implement order status request see [/api/v2/status/](https://doc.payneteasy.com/integration/API_commands/api_v2_status.html.md). Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.
(13) To implement callback with final status handling see [Connecting Party Callbacks](https://doc.payneteasy.com/integration/API_commands/merchant_callback_parameters.html.md).
### /registry/upload
#### Introduction
This API allows Manager to upload a file with adjustments for Merchant balance in Payment Gateway.
#### Adjustments parameters
Adjustments must be sent in archived tsv file format.
| Parameter | Description |
|----------------------|-----------------------------------------------------------------------------------|
| Credit amount | Credit amount. |
| Debit amount | Debit amount. |
| External ID | Adjustment external ID. |
| External Merchant ID | External merchant ID. Set in properties of merchant/manager. |
| Balance name | Balance name. If parameter is not set, default balance is automatically selected. |
#### File example
tsv file example:
```html
10.45 eid1 THIS_IS_EXT_MERCH_ID Global merchant balance
90.05 eid2 THIS_IS_EXT_MERCH_ID Global merchant balance
```
### Add Document
#### Introduction
Add Document allow to send request with document to attach it to the specific transaction. It is possible to attach any additional document to the existing transaction in the Payment Gateway. The attached document can be later downloaded from order details screen. This page describes how to attach the document to transaction by API.
#### Add Document Flow
```plantuml
skinparam roundcorner 20
skinparam sequenceArrowThickness 1
skinparam maxmessagesize 1200
skinparam sequenceParticipant underline
participant "Connecting Party" as A
participant "Payneteasy" as B
autonumber
hnote over A,B : Relevant Payment Flow
A -> A: Collect Documents
activate A
A -> B: Request to attach documents by Order ID
deactivate A
activate B
B -> B: Request confirmed
B -> B: Attach Document to transaction
activate A
B -> A: Document has been attached
deactivate B
deactivate A
```
(2) Each transaction in the System has assigned Order ID. Connecting Party makes upload document request to attach it to the specified transaction by Order ID, using [/api/v2/documents/add-document](https://doc.payneteasy.com/integration/API_commands/api_v2_add-document.html.md).
### Check sale
#### Introduction
Check sale is initiated through HTTPS POST request by using [URLs](#api-url-check-sale) and the [parameters](#api-parameters-check-sale).
Check sale is used for security purposes and allows Payneteasy to compare the data sent by Connecting Party’s app with the data stored on Connecting Party’s server.
It is highly recommended to respond with the actual information stored on Connecting Party’s server.
#### API URLs
> **Note:** This is an example of URL format on Connecting Party server.
| Connecting Party Server |
|----------------------------------------------------------------|
| https://proxy.connectingpartyserver.com/sale/{invoice Id}/check |
#### Request Parameters
| Parameter Name | Description | Value |
|--------------------------------------|----------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| consumer | | `Necessity`: Required `Type`: **Object** |
| consumer.device | | `Necessity`: Required `Type`: **Object** |
| consumer.device.serial Number | Consumer’s device serial number. | `Necessity`: Required `Type`: String `Length`: 1-50 |
| session | | `Necessity`: Required `Type`: **Object** |
| session.access Token | Consumer’s access token key sent by Connecting Party’s app. | `Necessity`: Required `Type`: String `Length`: 32-128 |
| session.nonce | Value sent by Connecting Party’s app. | `Necessity`: Required `Type`: String `Length`: 32-128 |
| session.signature | Value sent by Connecting Party’s app. | `Necessity`: Required `Type`: String `Length`: 32-128 |
| session.token | The session token of sale transaction. | `Necessity`: Required `Type`: String `Length`: 16-36 |
| source Of Funds | | `Necessity`: Optional `Type`: **Object** |
| source Of Funds.reference | | `Necessity`: Optional `Type`: **Object** |
| source Of Funds.reference.client Card Id | The source card reference identifier (on client side) if sent in Perform sale request. | `Necessity`: Optional `Type`: String `Length`: 1-128 |
#### Success Response Parameters
| Parameter Name | Description | Value |
|--------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------|
| invoice Id | Sale transaction identifier | `Necessity`: Required `Type`: String |
| session | | `Necessity`: Required `Type`: **Object** |
| session.check Signature | Checksum generated by hmac-sha1 (see [Signature computation](https://doc.payneteasy.com/integration/api_development_tools.html.md)) from the concatenation of the consumer.device.serial Number, session.nonce, endpoint Id, invoice Id, source Of Funds.reference.server Card Id (if present). | `Necessity`: Required `Type`: String |
| session.nonce | Unique random string generated by Connecting Party’s server in Initiate sale response. | `Necessity`: Required `Type`: String |
| session.token | The session token of sale transaction. | `Necessity`: Required `Type`: String |
| consumer.email | Сonsumer’s email address, if sent in original card mapping transaction. | `Necessity`: Optional `Type`: String |
| source Of Funds | | `Necessity`: Optional `Type`: **Object** |
| source Of Funds.reference | | `Necessity`: Optional `Type`: **Object** |
| source Of Funds.reference.server Card Id | The source card reference identifier (on server side). | `Necessity`: Optional `Type`: String |
| transaction.currency | Upper case letters (ISO 4217 alpha code). | `Necessity`: Optional `Type`: String |
| transaction.random Sum Centis | Random sum amount (for random sum check), 1.00 EUR = 100 centis. | `Necessity`: Optional `Type`: Integer |
#### Fail Response Parameters
| Parameter Name | Description | Value |
|------------------|------------------------------------------------------------------------------------------------------------|------------------------------|
| error | | `Type`: **Object** |
| error.cause | Cause of the error. Possible values: `FILTERED`, `INVALID_REQUEST`, `SERVER_FAILED`, `SERVER_UNAVAILABLE`. | `Type`: Enum |
| error.code | The unique error code. | `Type`: String |
| error.message | Description of the error. | `Type`: String |
| invoice Id | Sale transaction identifier. | `Type`: String |
#### Request Example
```json
{
"consumer": {
"device": {
"serialNumber": "string"
}
},
"session": {
"accessToken": "string",
"nonce": "string",
"signature": "string",
"token": "string"
},
"sourceOfFunds": {
"reference": {
"clientCardId": "string"
}
}
}
```
#### Success Response Example
```json
{
"consumer": {
"email": "string"
},
"invoiceId": "string",
"session": {
"checkSignature": "string",
"nonce": "string",
"token": "string"
},
"sourceOfFunds": {
"card": {
"expiry": {
"month": "integer",
"year": "integer"
},
"holder":{
"firstName": "string",
"lastName": "string"
},
"number": "string"
},
"reference": {
"serverCardId": "string",
}
},
"transaction": {
"currency": "string",
"randomSumCentis": "integer"
}
}
```
#### Fail Response Example
```json
{
"error": {
"cause": "enum",
"code": "string",
"message": "string"
},
"invoiceId": "string"
}
```
### Check transfer
#### Introduction
Check transfer is initiated through HTTPS POST request by using [URLs](#api-url-check-transfer) and the [parameters](#api-parameters-check-transfer).
Check transfer is used for security purposes and allows Payneteasy to compare the data sent by Connecting Party’s app with the data stored on Connecting Party’s server.
It is highly recommended to respond with the actual information stored on Connecting Party’s server.
#### API URLs
> **Note:** This is an example of URL format on Connecting Party server.
| Connecting Party Server |
|--------------------------------------------------------------------|
| https://proxy.connectingpartyserver.com/transfer/{invoice Id}/check |
#### Request Parameters
| Parameter Name | Description | Value |
|-------------------------------------------|-------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| consumer | | `Necessity`: Required `Type`: **Object** |
| consumer.device | | `Necessity`: Required `Type`: **Object** |
| consumer.device.serial Number | Consumer’s device serial number. | `Necessity`: Required `Type`: String `Length`: 1-50 |
| session | | `Necessity`: Required `Type`: **Object** |
| session.access Token | Consumer’s access token key sent by Connecting Party’s app. | `Necessity`: Required `Type`: String `Length`: 32-128 |
| session.nonce | Value sent by Connecting Party’s app. | `Necessity`: Required `Type`: String `Length`: 32-128 |
| session.signature | Value sent by Connecting Party’s app. | `Necessity`: Required `Type`: String `Length`: 32-128 |
| session.token | The session token of transfer transaction. | `Necessity`: Required `Type`: String `Length`: 16-36 |
| source Of Funds | | `Necessity`: Optional `Type`: **Object** |
| source Of Funds.reference | | `Necessity`: Optional `Type`: **Object** |
| source Of Funds.reference.client Card Id | The source card reference identifier (on client side) if sent in Perform Transfer request. | `Necessity`: Optional `Type`: String `Length`: 1-128 |
| destination Of Funds | | `Necessity`: Optional `Type`: **Object** |
| destination Of Funds.reference | | `Necessity`: Optional `Type`: **Object** |
| destination Of Funds.reference.client Card Id | The destination card reference identifier (on client side) if sent in Perform Transfer request. | `Necessity`: Optional `Type`: String `Length`: 1-128 |
#### Success Response Parameters
| Parameter Name | Description | Value |
|-------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------|
| invoice Id | Transfer transaction identifier. | `Necessity`: Required `Type`: String |
| session | | `Necessity`: Required `Type`: **Object** |
| session.check Signature | Checksum generated by hmac-sha1 (see [Signature computation](https://doc.payneteasy.com/integration/api_development_tools.html.md)) from the concatenation of the consumer.device.serial Number, session.nonce, destination Of Funds.reference.server Card Id (if present), endpoint Id, invoice Id, source Of Funds.reference.server Card Id (if present). | `Necessity`: Required `Type`: String |
| session.nonce | Unique random string generated by Connecting Party’s server in Initiate transfer response. | `Necessity`: Required `Type`: String |
| session.token | The session token of transfer transaction. | `Necessity`: Required `Type`: String |
| consumer.email | Consumer’s email address. | `Necessity`: Optional `Type`: String |
| destination Of Funds | | `Necessity`: Optional `Type`: **Object** |
| destination Of Funds.reference | | `Necessity`: Optional `Type`: **Object** |
| destination Of Funds.reference.server Card Id | The destination card reference identifier (on server side). | `Necessity`: Optional `Type`: String |
| source Of Funds | | `Necessity`: Optional `Type`: **Object** |
| source Of Funds.reference | | `Necessity`: Optional `Type`: **Object** |
| source Of Funds.reference.server Card Id | The source card reference identifier (on server side). | `Necessity`: Optional `Type`: String |
| transaction.currency | Upper case letters (ISO 4217 alpha code). | `Necessity`: Optional `Type`: String |
| transaction.random Sum Centis | Random sum amount (for random sum check), 1.00 EUR = 100 centis. | `Necessity`: Optional `Type`: Integer |
#### Fail Response Parameters
| Parameter Name | Description | Value |
|------------------|------------------------------------------------------------------------------------------------------------|------------------------------|
| error | | `Type`: **Object** |
| error.cause | Cause of the error. Possible values: `FILTERED`, `INVALID_REQUEST`, `SERVER_FAILED`, `SERVER_UNAVAILABLE`. | `Type`: Enum |
| error.code | The unique error code. | `Type`: String |
| error.message | Description of the error. | `Type`: String |
| invoice Id | Transfer transaction identifier. | `Type`: String |
#### Request Example
```json
{
"consumer": {
"device": {
"serialNumber": "string"
}
},
"destinationOfFunds": {
"reference": {
"clientCardId": "string"
}
},
"session": {
"accessToken": "string",
"nonce": "string",
"signature": "string",
"token": "string"
},
"sourceOfFunds": {
"reference": {
"clientCardId": "string"
}
}
}
```
#### Success Response Example
```json
{
"consumer": {
"email": "string"
},
"destinationOfFunds": {
"card": {
"number": "string"
},
"reference": {
"serverCardId": "string"
}
},
"invoiceId": "string",
"session": {
"checkSignature": "string",
"nonce": "string",
"token": "string"
},
"sourceOfFunds": {
"card": {
"expiry": {
"month": "integer",
"year": "integer"
},
"holder":{
"firstName": "string",
"lastName": "string"
},
"number": "string"
},
"reference": {
"serverCardId": "string",
}
},
"transaction": {
"currency": "string",
"randomSumCentis": "integer"
}
}
```
#### Fail Response Example
```json
{
"error": {
"cause": "enum",
"code": "string",
"message": "string"
},
"invoiceId": "string"
}
```
### Check verification
#### Introduction
Check verification is initiated through HTTPS POST request by using [URLs](#api-url-check-verification) and the [parameters](#api-parameters-check-verification).
Check verification is used for security purposes and allows Payneteasy to compare the data sent by Connecting Party’s app with the data stored on Connecting Party’s server.
It is highly recommended to respond with the actual information stored on Connecting Party’s server.
#### API URLs
> **Note:** This is an example of URL format on Connecting Party server.
| Connecting Party Server |
|------------------------------------------------------------------------|
| https://proxy.connectingpartyserver.com/verification/{invoice Id}/check |
#### Request Parameters
| Parameter Name | Description | Value |
|------------------------------|-------------------------------------------------------------|---------------------------------------------------------|
| consumer | | `Type`: **Object** |
| consumer.device | | `Type`: **Object** |
| consumer.device.serial Number | Consumer’s device serial number. | `Type`: String `Length`: 1-50 |
| session | | `Type`: **Object** |
| session.access Token | Consumer’s access token key sent by Connecting Party’s app. | `Type`: String `Length`: 32-128 |
| session.nonce | Value sent by Connecting Party’s app. | `Type`: String `Length`: 32-128 |
| session.signature | Value sent by Connecting Party’s app. | `Type`: String `Length`: 32-128 |
| session.token | The session token of verification transaction. | `Type`: String `Length`: 16-36 |
#### Success Response Parameters
| Parameter Name | Description | Value |
|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------|
| invoice Id | Verification transaction identifier. | `Necessity`: Required `Type`: String |
| session | | `Necessity`: Required `Type`: **Object** |
| session.check Signature | Checksum generated by hmac-sha1 (see [Signature computation](https://doc.payneteasy.com/integration/api_development_tools.html.md)) from the concatenation of consumer.device.serial Number, session.nonce, endpoint Id and invoice Id. | `Necessity`: Required `Type`: String |
| session.nonce | Unique random string generated by Connecting Party’s server in Initiate verification response. | `Necessity`: Required `Type`: String |
| session.token | The session token of verification transaction. | `Necessity`: Required `Type`: String |
| billing | | `Necessity`: Optional `Type`: **Object** |
| billing.address | | `Necessity`: Optional `Type`: **Object** |
| billing.address.city | City name. | `Necessity`: Optional `Type`: String |
| billing.address.country | ISO alpha3 country code. | `Necessity`: Optional `Type`: String |
| billing.address.postcode Zip | ZIP post code. | `Necessity`: Optional `Type`: String |
| billing.address.state | State is used if present. For example, Los Angeles is in CA state. | `Necessity`: Optional `Type`: String |
| billing.address.street | Street is used for district names and street names. | `Necessity`: Optional `Type`: String |
| billing.address.street2 | Street 2 is used for long addresses. Usually it contains apartment and building №. | `Necessity`: Optional `Type`: String |
| billing.phone | Customer’s contact phone number. | `Necessity`: Optional `Type`: String |
| consumer.birth Day | Consumer’s birth day in “ddMMyyyy” format. | `Necessity`: Optional `Type`: String |
| consumer.email | Consumer’s email address. | `Necessity`: Optional `Type`: String |
| consumer.ip Addresses | Consumer’s IP addresses. | `Necessity`: Optional `Type`: List |
| consumer.ip Addresses[] | Consumer’s IP address. | `Necessity`: Optional `Type`: String |
| transaction.currency | Upper case letters (ISO 4217 alpha code). | `Necessity`: Optional `Type`: String |
| transaction.random Sum Centis | Random sum amount (for random sum check), 1.00 EUR = 100 centis. | `Necessity`: Optional `Type`: Integer |
#### Fail Response Parameters
| Parameter Name | Description | Value |
|------------------|------------------------------------------------------------------------------------------------------------|------------------------------|
| error | | `Type`: **Object** |
| error.cause | Cause of the error. Possible values: `FILTERED`, `INVALID_REQUEST`, `SERVER_FAILED`, `SERVER_UNAVAILABLE`. | `Type`: Enum |
| error.code | The unique error code. | `Type`: String |
| error.message | Description of the error. | `Type`: String |
| invoice Id | Verification transaction identifier. | `Type`: String |
#### Request Example
```json
{
"consumer": {
"device": {
"serialNumber": "string"
}
},
"session": {
"accessToken": "string",
"nonce": "string",
"signature": "string",
"token": "string"
}
}
```
#### Success Response Example
```json
{
"billing": {
"address": {
"city": "string",
"country": "string",
"postcodeZip": "string",
"state": "string",
"street": "string",
"street2": "string"
},
"phone": "string"
},
"consumer": {
"birthDay": "string",
"email": "string",
"ipAddresses": ["string"]
},
"invoiceId": "string",
"session": {
"checkSignature": "string",
"nonce": "string",
"token": "string"
},
"transaction": {
"currency": "string",
"randomSumCentis": "integer"
}
}
```
#### Fail Response Example
```json
{
"error": {
"cause": "enum",
"code": "string",
"message": "string"
},
"invoiceId": "string"
}
```
### Complete Transfer
#### Introduction
Complete transfer is initiated through HTTPS POST request by using [URLs](#api-url-complete-transfer) and the [parameters](#api-parameters-complete-transfer).
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|---------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/dapi/v1/transfer/{endpoint Id}/{invoice Id}/{assigned Id} | https://gate.payneteasy.eu/paynet/dapi/v1/transfer/{endpoint Id}/{invoice Id}/{assigned Id} |
#### Request Parameters
| Parameter Name | Description | Value |
|---------------------|---------------------------------------------------|------------------------------|
| session | | `Type`: **Object** |
| session.access Token | The session access token of transfer transaction. | `Type`: String |
| session.token | The session token of transfer transaction. | `Type`: String |
#### Success Response Parameters
| Parameter Name | Description | Value |
|------------------|--------------------------------------------|------------------------------|
| invoice Id | Transfer transaction identifier. | `Type`: String |
| session | | `Type`: **Object** |
| session.token | The session token of transfer transaction. | `Type`: String |
#### Fail Response Parameters
| Parameter Name | Description | Value |
|------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------|
| error | | `Type`: **Object** |
| error.cause | Cause of the error. Possible values: `INVALID_REQUEST`, `INVALID_CONFIGURATION`, `INTERNAL_ERROR`, `PROCESSING_FAILED`. | `Type`: Enum |
| error.code | The unique error code. | `Type`: String |
| error.message | Description of the error. | `Type`: String |
| invoice Id | Transfer transaction identifier. | `Type`: String |
#### Request Example
```json
{
"session": {
"accessToken": "string",
"token": "string"
}
}
```
#### Success Response Example
```json
{
"invoiceId": "string",
"session": {
"token": "string"
}
}
```
#### Fail Response Example
```json
{
"error": {
"cause": "enum",
"code": "string",
"message": "string"
},
"invoiceId": "string"
}
```
### Development tools
#### Introduction
#### Signature computation
The signature is being used to ensure that it is Connecting Party (and not a fraudster) who sends the information to Payneteasy.
Signatures in DAPI are computed using HMAC_SHA1 algorithm. Key is derived in the following way:
1. Take Connecting Party Control Key
2. Remove dashes from it
3. Unhex the result to binary
The correct signature values for all types of transactions supported by DAPI in the debugging tool below:
#### Example code and SDK
There are several solutions available on Git Hub, which were developed for integration with Payneteasy on Android and iOS platforms via DAPI.
### Initiate sale
#### Introduction
Initiate sale is initiated through HTTPS POST request by using [URLs](#api-url-initiate-sale) and the [parameters](#api-parameters-initiate-sale).
To initiate sale, Connecting Party’s app sends {access Token} with transaction amount and other device parameters to Connecting Party’s server, which are used to start a session with unique random {nonce} and encrypted {signature}.
In response Connecting Party’s server also provides information about invoice in Connecting Party’s system and endpoint in Payneteasy.
#### API URLs
> **Note:** This is an example of URL format on Connecting Party server.
| Connecting Party Server |
|------------------------------------------------------------|
| https://proxy.connectingpartyserver.com/sale/initiate-sale |
#### Request Parameters
| Parameter Name | Description | Value |
|------------------------------|-----------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| consumer | | `Necessity`: Required `Type`: **Object** |
| consumer.device | | `Necessity`: Required `Type`: **Object** |
| consumer.device.serial Number | Consumer’s device serial number. | `Necessity`: Required `Type`: String `Length`: 1-50 |
| transaction | | `Necessity`: Required `Type`: **Object** |
| transaction.amount Centis | Transaction amount, 1.00 EUR = 100 centis. | `Necessity`: Required `Type`: Integer |
| transaction.currency | Upper case letters (ISO 4217 alpha code). | `Necessity`: Required `Type`: String `Length`: 3 |
| session | | `Necessity`: Required `Type`: **Object** |
| session.access Token | Access token key received in Optional consumer authentication. | `Necessity`: Required `Type`: String `Length`: 32-128 |
| consumer.device.imei | Consumer’s device international mobile equipment identity. | `Necessity`: Optional `Type`: String `Length`: 14-16 |
| location | | `Necessity`: Optional `Type`: **Object** |
| location.lat | The latitude specified in the range of -90.0 through +90.0, both inclusive. | `Necessity`: Optional `Type`: Double |
| location.lng | The longitude specified in the range -180.0 through +180.0, both inclusive. | `Necessity`: Optional `Type`: Double |
| consumer.ip Addresses | Consumer’s IP addresses. | `Necessity`: Optional `Type`: List |
| consumer.ip Addresses[] | Consumer’s IP address. | `Necessity`: Optional `Type`: String `Length`: 7-15 |
#### Success Response Parameters
| Parameter Name | Description | Value |
|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------|
| endpoint Id | Entry point identifier for sale transaction. | `Necessity`: Required `Type`: String |
| invoice Id | Transfer transaction identifier. | `Necessity`: Required `Type`: String |
| session | | `Necessity`: Required `Type`: **Object** |
| session.nonce | Unique random string generated by Connecting Party’s server. | `Necessity`: Required `Type`: String |
| session.signature | Checksum generated by hmac-sha1 (see [Signature computation](https://doc.payneteasy.com/integration/api_development_tools.html.md)) from the concatenation of the access Token, consumer.device.serial Number, endpoint Id, session.nonce, invoice Id, transaction.amount Centis and the transaction.currency. | `Necessity`: Required `Type`: String |
#### Fail Response Parameters
| Parameter Name | Description | Value |
|------------------|------------------------------------------------------------------------------------------------------------|------------------------------|
| error | | `Type`: **Object** |
| error.cause | Cause of the error. Possible values: `FILTERED`, `INVALID_REQUEST`, `SERVER_FAILED`, `SERVER_UNAVAILABLE`. | `Type`: Enum |
| error.code | The unique error code. | `Type`: String |
| error.message | Description of the error. | `Type`: String |
#### Request Example
```json
{
"consumer": {
"device": {
"imei": "string",
"serialNumber": "string"
},
"ipAddresses": ["string"]
},
"location": {
"lat": "double",
"lng": "double"
},
"session": {
"accessToken": "string"
},
"transaction": {
"amountCentis": "integer",
"currency": "string"
}
}
```
#### Success Response Example
```json
{
"endpointId": "string",
"invoiceId": "string",
"session": {
"nonce": "string",
"signature": "string"
}
}
```
#### Fail Response Example
```json
{
"error": {
"cause": "enum",
"code": "string",
"message": "string"
}
}
```
### Initiate transfer
#### Introduction
Initiate transfer is initiated through HTTPS POST request by using [URLs](#api-url-initiate-transfer) and the [parameters](#api-parameters-initiate-transfer).
To initiate funds transfer, Connecting Party’s app sends {access Token} with transaction amount and other device parameters to Connecting Party’s server, which are used to start a session with unique random {nonce} and encrypted {signature}.
In response Connecting Party’s server also provides information about invoice in Connecting Party’s system and endpoint in Payneteasy.
The Connecting Party’s server may also respond with the transaction’s commission.
#### API URLs
> **Note:** This is an example of URL format on Connecting Party server.
| Connecting Party Server |
|--------------------------------------------------------------------|
| https://proxy.connectingpartyserver.com/transfer/initiate-transfer |
#### Request Parameters
| Parameter Name | Description | Value |
|------------------------------|-----------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| consumer | | `Necessity`: Required `Type`: **Object** |
| consumer.device | | `Necessity`: Required `Type`: **Object** |
| consumer.device.serial Number | Consumer’s device serial number. | `Necessity`: Required `Type`: String `Length`: 1-50 |
| transaction | | `Necessity`: Required `Type`: **Object** |
| transaction.amount Centis | Transaction amount, 1.00 EUR = 100 centis. | `Necessity`: Required `Type`: Integer |
| transaction.currency | Upper case letters (ISO 4217 alpha code). | `Necessity`: Required `Type`: String `Length`: 3 |
| session | | `Necessity`: Required `Type`: **Object** |
| session.access Token | Access token key received in Optional consumer authentication. | `Necessity`: Required `Type`: String `Length`: 32-128 |
| consumer.device.imei | Consumer’s device international mobile equipment identity. | `Necessity`: Optional `Type`: String `Length`: 14-16 |
| location | | `Necessity`: Optional `Type`: **Object** |
| location.lat | The latitude specified in the range of -90.0 through +90.0, both inclusive. | `Type`: Double |
| location.lng | The longitude specified in the range -180.0 through +180.0, both inclusive. | `Type`: Double |
| consumer.ip Addresses | Consumer’s IP addresses. | `Type`: List |
| consumer.ip Addresses[] | Consumer’s IP address. | `Necessity`: Optional `Type`: String `Length`: 7-15 |
| from Bin | Source of funds card BIN (first 6 digits of card number) may be used to display pre-calculated commission. | `Necessity`: Optional `Type`: String `Length`: 6 |
| to Bin | Destination of funds card BIN (first 6 digits of card number) may be used to display pre-calculated commission. | `Necessity`: Optional `Type`: String `Length`: 6 |
#### Success Response Parameters
| Parameter Name | Description | Value |
|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------|
| endpoint Id | Entry point identifier for transfer transaction. | `Necessity`: Required `Type`: String |
| invoice Id | Transfer transaction identifier. | `Necessity`: Required `Type`: String |
| session | | `Necessity`: Required `Type`: **Object** |
| session.nonce | Unique random string generated by Connecting Party’s server. | `Necessity`: Required `Type`: String |
| session.signature | Checksum generated by hmac-sha1 (see [Signature computation](https://doc.payneteasy.com/integration/api_development_tools.html.md)) from the concatenation of the access Token, consumer.device.serial Number, endpoint Id, session.nonce, invoice Id, transaction.amount Centis and the transaction.currency. | `Necessity`: Required `Type`: String |
| rates | | `Necessity`: Optional `Type`: **Object** |
| rates.min | Possible minimum commission amount. | `Necessity`: Optional `Type`: String |
| rates.max | Possible maximum commission amount. | `Necessity`: Optional `Type`: String |
#### Fail Response Parameters
| Parameter Name | Description | Value |
|------------------|------------------------------------------------------------------------------------------------------------|------------------------------|
| error | | `Type`: **Object** |
| error.cause | Cause of the error. Possible values: `FILTERED`, `INVALID_REQUEST`, `SERVER_FAILED`, `SERVER_UNAVAILABLE`. | `Type`: Enum |
| error.code | The unique error code. | `Type`: String |
| error.message | Description of the error. | `Type`: String |
#### Request Example
```json
{
"consumer": {
"device": {
"imei": "string",
"serialNumber": "string"
},
"ipAddresses": ["string"]
},
"location": {
"lat": "double",
"lng": "double"
},
"session": {
"accessToken": "string"
},
"transaction": {
"amountCentis": "integer",
"currency": "string"
}
}
```
#### Success Response Example
```json
{
"endpointId": "string",
"invoiceId": "string",
"rates": {
"min": "string",
"max": "string"
},
"session": {
"nonce": "string",
"signature": "string"
}
}
```
#### Fail Response Example
```json
{
"error": {
"cause": "enum",
"code": "string",
"message": "string"
}
}
```
### Initiate verification
#### Introduction
Initiate verification is initiated through HTTPS POST request by using [URLs](#api-url-initiate-verification) and the [parameters](#api-parameters-initiate-verification).
To initiate card verification, Connecting Party’s app sends {access Token} with other device parameters to Connecting Party’s server. These parameters are used to start a session with unique random {nonce} and encrypted {signature}. In response Connecting Party’s server also provides information about {invoice Id} in Connecting Party’s system and {endpoint Id} in Payneteasy.
#### API URLs
> **Note:** This is an example of URL format on Connecting Party server.
| Connecting Party Server |
|----------------------------------------------------------------------------|
| https://proxy.connectingpartyserver.com/verification/initiate-verification |
#### Request Parameters
| Parameter Name | Description | Value |
|------------------------------|---------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| consumer | | `Necessity`: Required `Type`: **Object** |
| consumer.device | | `Necessity`: Required `Type`: **Object** |
| consumer.device.serial Number | Consumer’s device serial number. | `Necessity`: Required `Type`: String `Length`: 1-50 |
| transaction | | `Necessity`: Required `Type`: **Object** |
| transaction.currency | Upper case letters (ISO 4217 alpha code). | `Necessity`: Required `Type`: String `Length`: 3 |
| session | | `Necessity`: Required `Type`: **Object** |
| session.access Token | Access token key received in Optional consumer authentication. | `Necessity`: Required `Type`: String `Length`: 32-128 |
| consumer.device.imei | Consumer’s device international mobile equipment identity. | `Necessity`: Optional `Type`: String `Length`: 14-16 |
| location | | `Necessity`: Optional `Type`: **Object** |
| location.lat | The latitude specified in the range of -90.0 through +90.0, both inclusive. | `Necessity`: Optional `Type`: Double |
| location.lng | The longitude specified in the range -180.0 through +180.0, both inclusive. | `Necessity`: Optional `Type`: Double |
| consumer.ip Addresses | Consumer’s IP addresses. | `Necessity`: Optional `Type`: List |
| consumer.ip Addresses[] | Consumer’s IP address. | `Necessity`: Optional `Type`: String `Length`: 7-15 |
#### Success Response Parameters
| Parameter Name | Description | Value |
|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------|
| endpoint Id | Entry point identifier for verification transaction. | `Type`: String |
| invoice Id | Verification transaction identifier. | `Type`: String |
| session | | `Type`: **Object** |
| session.nonce | Unique random string generated by Connecting Party’s server. | `Type`: String |
| session.signature | Checksum generated by hmac-sha1 (see [Signature computation](https://doc.payneteasy.com/integration/api_development_tools.html.md)) from the concatenation of access Token, consumer.device.serial Number, endpoint Id, session.nonce, invoice Id and transaction.currency. | `Type`: String |
#### Fail Response Parameters
| Parameter Name | Description | Value |
|------------------|------------------------------------------------------------------------------------------------------------|------------------------------|
| error | | `Type`: **Object** |
| error.cause | Cause of the error. Possible values: `FILTERED`, `INVALID_REQUEST`, `SERVER_FAILED`, `SERVER_UNAVAILABLE`. | `Type`: Enum |
| error.code | The unique error code. | `Type`: String |
| error.message | Description of the error. | `Type`: String |
#### Request Example
```json
{
"consumer": {
"device": {
"imei": "string",
"serialNumber": "string"
},
"ipAddresses": ["string"]
},
"location": {
"lat": "double",
"lng": "double"
},
"session": {
"accessToken": "string"
},
"transaction": {
"currency": "string"
}
}
```
#### Success Response Example
```json
{
"endpointId": "string",
"invoiceId": "string",
"session": {
"nonce": "string",
"signature": "string"
}
}
```
#### Fail Response Example
```json
{
"error": {
"cause": "enum",
"code": "string",
"message": "string"
}
}
```
### Mobile Device Payneteasy API
### Mobile Device Connecting Party Server API
### Perform sale
#### Introduction
Perform sale is initiated through HTTPS POST request by using [URLs](#api-url-perform-sale) and the [parameters](#api-parameters-perform-sale).
On this stage Connecting Party’s app sends cardholder, device, session data and other parameters straight to Payneteasy to perform sale transaction.
A lot of criteria checks and filters may be applied, such as BIN, currency, country, blacklisted or not, etc. Depending on the integration, these settings may be customizable.
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|----------------------------------------------------------------------------|-------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/dapi/v1/sale/{endpoint Id}/{invoice Id} | https://gate.payneteasy.eu/paynet/dapi/v1/sale/{endpoint Id}/{invoice Id} |
#### Request Parameters
| Parameter Name | Description | Value |
|---------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| consumer | | `Necessity`: Required `Type`: **Object** |
| consumer.device | | `Necessity`: Required `Type`: **Object** |
| consumer.device.serial Number | Consumer’s device serial number. | `Necessity`: Required `Type`: String `Length`: 1-50 |
| consumer.email | Сonsumer’s email address, if sent in original card mapping transaction and card reference is being used instead of cardholder data. | `Necessity`: Required `Type`: String `Length`: 3-128 |
| session | | `Necessity`: Required `Type`: **Object** |
| session.access Token | Access token key received in Optional consumer authentication. | `Necessity`: Required `Type`: String `Length`: 32-128 |
| session.nonce | Value received in initiate sale response. | `Necessity`: Required `Type`: String `Length`: 32-128 |
| session.signature | Value received in initiate sale response. | `Necessity`: Required `Type`: String `Length`: 32-128 |
| source Of Funds | | `Necessity`: Required `Type`: **Object** |
| source Of Funds.card | Only one of these subtypes (card, reference) should be used. | `Necessity`: Required `Type`: **Object** |
| source Of Funds.card.expiry | | `Necessity`: Required `Type`: **Object** |
| source Of Funds.card.expiry.month | Source Card expiration month. | `Necessity`: Required `Type`: Integer `Length`: 2 |
| source Of Funds.card.expiry.year | Source Card expiration year. | `Necessity`: Required `Type`: Integer `Length`: 4 |
| source Of Funds.card.holder | | `Necessity`: Required `Type`: **Object** |
| source Of Funds.card.holder.first Name | Cardholder’s first name. | `Necessity`: Required `Type`: String `Length`: 1-50 |
| source Of Funds.card.holder.last Name | Cardholder’s last name. | `Necessity`: Required `Type`: String `Length`: 1-50 |
| source Of Funds.card.holder.printed Name | Cardholder’s printed name (first and last name together). May be used instead of first Name + last Name. | `Necessity`: Required `Type`: String `Length`: 1-50 |
| source Of Funds.card.number | Source card number (PAN). | `Necessity`: Required `Type`: String `Length`: 9-19 |
| source Of Funds.card.security Code | Source card security code (CVV). | `Necessity`: Required `Type`: String `Length`: 3-4 |
| source Of Funds.reference | only one of these subtypes (card, reference) should be used. | `Necessity`: Required `Type`: **Object** |
| source Of Funds.reference.client Card Id | Source card reference identifier (on client side). | `Necessity`: Required `Type`: String `Length`: 1-128 |
| source Of Funds.reference.security Code | Source card security code (CVV). | `Necessity`: Required `Type`: String `Length`: 3-4 |
| transaction | | `Necessity`: Required `Type`: **Object** |
| transaction.amount Centis | Transaction amount, 1.00 EUR = 100 centis. | `Necessity`: Required `Type`: Integer |
| transaction.currency | Upper case letters (ISO 4217 alpha code). | `Necessity`: Required `Type`: String `Length`: 3 |
| location | | `Necessity`: Optional `Type`: **Object** |
| location.lat | The latitude specified in the range of -90.0 through +90.0, both inclusive. | `Necessity`: Optional `Type`: Double |
| location.lng | The longitude specified in the range -180.0 through +180.0, both inclusive. | `Necessity`: Optional `Type`: Double |
| billing | | `Necessity`: Optional `Type`: **Object** |
| billing.address | | `Necessity`: Optional `Type`: **Object** |
| billing.address.city | City name. | `Necessity`: Optional `Type`: String `Length`: 1-100 |
| billing.address.country | ISO alpha3 country code. | `Necessity`: Optional `Type`: String `Length`: 3 |
| billing.address.postcode Zip | ZIP post code. | `Necessity`: Optional `Type`: String `Length`: 1-10 |
| billing.address.state | State is used if present. For example, Los Angeles is in CA state. | `Necessity`: Optional `Type`: String `Length`: 2-3 |
| billing.address.street | Street is used for district names and street names. | `Necessity`: Optional `Type`: String `Length`: 1-50 |
| billing.address.street2 | Street 2 is used for long addresses. Usually it contains apartment and building №. | `Necessity`: Optional `Type`: String `Length`: 1-50 |
| billing.phone | Сonsumer’s contact phone number. | `Necessity`: Optional `Type`: String `Length`: 1-20 |
| consumer.birth Day | Сonsumer’s birth day in “ddMMyyyy” format. | `Necessity`: Optional `Type`: String `Length`: 8 |
| consumer.device.imei | Сonsumer’s device international mobile equipment identity. | `Necessity`: Optional `Type`: String `Length`: 14-16 |
| consumer.ip Addresses | Сonsumer’s IP addresses. | `Necessity`: Optional `Type`: List |
| consumer.ip Addresses[] | Сonsumer’s IP address. | `Necessity`: Optional `Type`: String `Length`: 7-15 |
| order | | `Necessity`: Optional `Type`: **Object** |
| order.description | Brief transaction description. May be mandatory for certain Acquirer Banks. | `Necessity`: Optional `Type`: String `Length`: 128 |
| order.site Url | URL of website associated with the transaction. | `Necessity`: Optional `Type`: String `Length`: 128 |
| order.purpose | May be used for better transaction control or additional checks. | `Necessity`: Optional `Type`: String `Length`: 128 |
#### Success Response Parameters
| Parameter Name | Description | Value |
|------------------|----------------------------------------|------------------------------|
| invoice Id | Sale transaction identifier. | `Type`: String |
| session | | `Type`: **Object** |
| session.token | The session token of sale transaction. | `Type`: String |
#### Fail Response Parameters
| Parameter Name | Description | Value |
|------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------|
| error | | `Type`: **Object** |
| error.cause | Cause of the error. Possible values: `INVALID_REQUEST`, `INVALID_CONFIGURATION`, `INTERNAL_ERROR`, `PROCESSING_FAILED`. | `Type`: Enum |
| error.code | The unique error code. | `Type`: String |
| error.message | Description of the error. | `Type`: String |
| invoice Id | Sale transaction identifier. | `Type`: String |
#### Request Example
```json
{
"billing": {
"address": {
"city": "string",
"country": "string",
"postcodeZip": "string",
"state": "string",
"street": "string",
"street2": "string"
},
"phone": "string"
},
"consumer": {
"birthDay": "string",
"device": {
"imei": "string",
"serialNumber": "string"
},
"email": "string",
"ipAddresses": ["string"]
},
"location": {
"lat": "double",
"lng": "double"
},
"order": {
"description": "string",
"siteUrl": "string",
"purpose": "string"
},
"session": {
"accessToken": "string",
"nonce": "string",
"signature": "string"
},
"sourceOfFunds": {
"card": {
"expiry": {
"month": "integer",
"year": "integer"
},
"holder":{
"firstName": "string",
"lastName": "string"
},
"number": "string",
"securityCode": "string"
},
"reference": {
"clientCardId": "string",
"securityCode": "string"
}
},
"transaction": {
"amountCentis": "integer",
"currency": "string"
}
}
```
#### Success Response Example
```json
{
"invoiceId": "string",
"session": {
"token": "string"
}
}
```
#### Fail Response Example
```json
{
"error": {
"cause": "enum",
"code": "string",
"message": "string"
},
"invoiceId": "string"
}
```
### Perform transfer
#### Introduction
Perform transfer is initiated through HTTPS POST request by using [URLs](#api-url-perform-transfer) and the [parameters](#api-parameters-perform-transfer).
On this stage Connecting Party’s app sends cardholder, device, session data and other parameters straight to Payneteasy to perform funds transfer from card to card.
A lot of criteria checks and filters may be applied, such as BIN, currency, country, blacklisted or not, etc. Depending on the integration, these settings may be customizable.
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|--------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/dapi/v1/transfer/{endpoint Id}/{invoice Id} | https://gate.payneteasy.eu/paynet/dapi/v1/transfer/{endpoint Id}/{invoice Id} |
#### Request Parameters
| Parameter Name | Description | Value |
|-------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| consumer | | `Necessity`: Required `Type`: **Object** |
| consumer.device | | `Necessity`: Required `Type`: **Object** |
| consumer.device.serial Number | Consumer’s device serial number. | `Necessity`: Required `Type`: String `Length`: 1-50 |
| consumer.email | Сonsumer’s email address, if sent in original card mapping transaction and card reference is being used instead of cardholder data. | `Necessity`: Required `Type`: String `Length`: 3-128 |
| destination Of Funds | | `Necessity`: Required `Type`: **Object** |
| destination Of Funds.card | Only one of these subtypes (card, reference) should be used. | `Necessity`: Required `Type`: **Object** |
| destination Of Funds.card.number | Destination card number (PAN). | `Necessity`: Required `Type`: String `Length`: 9-19 |
| destination Of Funds.reference | Only one of these subtypes (card, reference) should be used. | `Necessity`: Required `Type`: **Object** |
| destination Of Funds.reference.client Card Id | Destination card reference identifier (on client side). | `Necessity`: Required `Type`: String `Length`: 1-128 |
| session | | `Necessity`: Required `Type`: **Object** |
| session.access Token | Access token key received in Optional consumer authentication. | `Necessity`: Required `Type`: String `Length`: 32-128 |
| session.nonce | Value received in Initiate transfer response. | `Necessity`: Required `Type`: String `Length`: 32-128 |
| session.signature | Value received in Initiate transfer response. | `Necessity`: Required `Type`: String `Length`: 32-128 |
| source Of Funds | | `Necessity`: Required `Type`: **Object** |
| source Of Funds.card | Only one of these subtypes (card, reference) should be used. | `Necessity`: Required `Type`: **Object** |
| source Of Funds.card.expiry | | `Necessity`: Required `Type`: **Object** |
| source Of Funds.card.expiry.month | Source Card expiration month. | `Necessity`: Required `Type`: Integer `Length`: 2 |
| source Of Funds.card.expiry.year | Source Card expiration year. | `Necessity`: Required `Type`: Integer `Length`: 4 |
| source Of Funds.card.holder | | `Necessity`: Required `Type`: **Object** |
| source Of Funds.card.holder.first Name | Cardholder’s first name. | `Necessity`: Required `Type`: String `Length`: 1-50 |
| source Of Funds.card.holder.last Name | Cardholder’s last name. | `Necessity`: Required `Type`: String `Length`: 1-50 |
| source Of Funds.card.holder.printed Name | Cardholder’s printed name (first and last name together). May be used instead of first Name + last Name. | `Necessity`: Required `Type`: String `Length`: 1-50 |
| source Of Funds.card.number | Source card number (PAN). | `Necessity`: Required `Type`: String `Length`: 9-19 |
| source Of Funds.card.security Code | Source card security code (CVV). | `Necessity`: Required `Type`: String `Length`: 3-4 |
| source Of Funds.reference | only one of these subtypes (card, reference) should be used. | `Necessity`: Required `Type`: **Object** |
| source Of Funds.reference.client Card Id | Source card reference identifier (on client side). | `Necessity`: Required `Type`: String `Length`: 1-128 |
| source Of Funds.reference.security Code | Source card security code (CVV). | `Necessity`: Required `Type`: String `Length`: 3-4 |
| transaction | | `Necessity`: Required `Type`: **Object** |
| transaction.amount Centis | Transaction amount, 1.00 EUR = 100 centis. | `Necessity`: Required `Type`: Integer |
| transaction.currency | Upper case letters (ISO 4217 alpha code). | `Necessity`: Required `Type`: String `Length`: 3 |
| location | | `Necessity`: Optional `Type`: **Object** |
| location.lat | The latitude specified in the range of -90.0 through +90.0, both inclusive. | `Necessity`: Optional `Type`: Double |
| location.lng | The longitude specified in the range -180.0 through +180.0, both inclusive. | `Necessity`: Optional `Type`: Double |
| billing | | `Necessity`: Optional `Type`: **Object** |
| billing.address | | `Necessity`: Optional `Type`: **Object** |
| billing.address.city | City name. | `Necessity`: Optional `Type`: String `Length`: 1-100 |
| billing.address.country | ISO alpha3 country code. | `Necessity`: Optional `Type`: String `Length`: 3 |
| billing.address.postcode Zip | ZIP post code. | `Necessity`: Optional `Type`: String `Length`: 1-10 |
| billing.address.state | State is used if present. For example, Los Angeles is in CA state. | `Necessity`: Optional `Type`: String `Length`: 2-3 |
| billing.address.street | Street is used for district names and street names. | `Necessity`: Optional `Type`: String `Length`: 1-50 |
| billing.address.street2 | Street 2 is used for long addresses. Usually it contains apartment and building №. | `Necessity`: Optional `Type`: String `Length`: 1-50 |
| billing.phone | Сonsumer’s contact phone number. | `Necessity`: Optional `Type`: String `Length`: 1-20 |
| consumer.birth Day | Сonsumer’s birth day in “ddMMyyyy” format. | `Necessity`: Optional `Type`: String `Length`: 8 |
| consumer.device.imei | Сonsumer’s device international mobile equipment identity. | `Necessity`: Optional `Type`: String `Length`: 14-16 |
| consumer.ip Addresses | Сonsumer’s IP addresses. | `Necessity`: Optional `Type`: List |
| consumer.ip Addresses[] | Сonsumer’s IP address. | `Necessity`: Optional `Type`: String `Length`: 7-15 |
| order | | `Necessity`: Optional `Type`: **Object** |
| order.description | Brief transaction description. May be mandatory for certain Acquirer Banks. | `Necessity`: Optional `Type`: String `Length`: 128 |
| order.site Url | URL of website associated with the transaction. | `Necessity`: Optional `Type`: String `Length`: 128 |
| order.purpose | May be used for better transaction control or additional checks. | `Necessity`: Optional `Type`: String `Length`: 128 |
#### Success Response Parameters
| Parameter Name | Description | Value |
|------------------|--------------------------------------------|------------------------------|
| invoice Id | Transfer transaction identifier. | `Type`: String |
| session | | `Type`: **Object** |
| session.token | The session token of transfer transaction. | `Type`: String |
#### Fail Response Parameters
| Parameter Name | Description | Value |
|------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------|
| error | | `Type`: **Object** |
| error.cause | Cause of the error. Possible values: `INVALID_REQUEST`, `INVALID_CONFIGURATION`, `INTERNAL_ERROR`, `PROCESSING_FAILED`. | `Type`: Enum |
| error.code | The unique error code. | `Type`: String |
| error.message | Description of the error. | `Type`: String |
| invoice Id | Transfer transaction identifier. | `Type`: String |
#### Request Example
```json
{
"billing": {
"address": {
"city": "string",
"country": "string",
"postcodeZip": "string",
"state": "string",
"street": "string",
"street2": "string"
},
"phone": "string"
},
"consumer": {
"birthDay": "string",
"device": {
"imei": "string",
"serialNumber": "string"
},
"email": "string",
"ipAddresses": ["string"]
},
"destinationOfFunds": {
"card": {
"number": "string",
},
"reference": {
"clientCardId": "string"
}
},
"location": {
"lat": "double",
"lng": "double"
},
"order": {
"description": "string",
"siteUrl": "string",
"purpose": "string"
},
"session": {
"accessToken": "string",
"nonce": "string",
"signature": "string"
},
"sourceOfFunds": {
"card": {
"expiry": {
"month": "integer",
"year": "integer"
},
"holder":{
"firstName": "string",
"lastName": "string"
},
"number": "string",
"securityCode": "string"
},
"reference": {
"clientCardId": "string",
"securityCode": "string"
}
},
"transaction": {
"amountCentis": "integer",
"currency": "string"
}
}
```
#### Success Response Example
```json
{
"invoiceId": "string",
"session": {
"token": "string"
}
}
```
#### Fail Response Example
```json
{
"error": {
"cause": "enum",
"code": "string",
"message": "string"
},
"invoiceId": "string"
}
```
### Perform validation
#### Introduction
Perform validation is initiated through HTTPS POST request by using [URLs](#api-url-perform-verification) and the [parameters](#api-parameters-perform-verification).
Connecting Party’s app sends cardholder, device, session data and other parameters straight to Payneteasy to check the card for being valid.
A lot of criteria checks and filters may be applied, such as BIN, currency, country, blacklisted or not, etc. Depending on the integration, these settings may be customizable.
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|------------------------------------------------------------------------------------|---------------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/dapi/v1/verification/{endpoint Id}/{invoice Id} | https://gate.payneteasy.eu/paynet/dapi/v1/verification/{endpoint Id}/{invoice Id} |
#### Request Parameters
| Parameter Name | Description | Value |
|-------------------------------|--------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| consumer | | `Necessity`: Required `Type`: **Object** |
| consumer.device | | `Necessity`: Required `Type`: **Object** |
| consumer.device.serial Number | Consumer’s device serial number. | `Necessity`: Required `Type`: String `Length`: 1-50 |
| consumer.email | Сonsumer’s email address. | `Necessity`: Required `Type`: String `Length`: 3-128 |
| session | | `Necessity`: Required `Type`: **Object** |
| session.access Token | Access token key received in Optional consumer authentication. | `Necessity`: Required `Type`: String `Length`: 32-128 |
| session.nonce | Value received in Initial verification response. | `Necessity`: Required `Type`: String `Length`: 32-128 |
| session.signature | Value received in Initial verification response. | `Necessity`: Required `Type`: String `Length`: 32-128 |
| source Card | | `Necessity`: Required `Type`: **Object** |
| source Card.expiry | | `Necessity`: Required `Type`: **Object** |
| source Card.expiry.month | Source Card expiration month. | `Necessity`: Required `Type`: Integer `Length`: 2 |
| source Card.expiry.year | Source Card expiration year. | `Necessity`: Required `Type`: Integer `Length`: 4 |
| source Card.holder | | `Necessity`: Required `Type`: **Object** |
| source Card.holder.first Name | Cardholder’s first name. | `Necessity`: Required `Type`: String `Length`: 1-50 |
| source Card.holder.last Name | Cardholder’s last name. | `Necessity`: Required `Type`: String `Length`: 1-50 |
| source Card.holder.printed Name | Cardholder’s printed name (first and last name together). May be used instead of first Name + last Name. | `Necessity`: Required `Type`: String `Length`: 1-50 |
| source Card.number | Source card number (PAN). | `Necessity`: Required `Type`: String `Length`: 9-19 |
| source Card.security Code | Source card security code (CVV). | `Necessity`: Required `Type`: String `Length`: 3-4 |
| transaction | | `Necessity`: Required `Type`: **Object** |
| transaction.currency | Upper case letters (ISO 4217 alpha code). | `Necessity`: Required `Type`: String `Length`: 3 |
| location | | `Necessity`: Optional `Type`: **Object** |
| location.lat | The latitude specified in the range of -90.0 through +90.0, both inclusive. | `Necessity`: Optional `Type`: Double |
| location.lng | The longitude specified in the range -180.0 through +180.0, both inclusive. | `Necessity`: Optional `Type`: Double |
| billing | | `Necessity`: Optional `Type`: **Object** |
| billing.address | | `Necessity`: Optional `Type`: **Object** |
| billing.address.city | City name. | `Necessity`: Optional `Type`: String `Length`: 1-100 |
| billing.address.country | ISO alpha3 country code. | `Necessity`: Optional `Type`: String `Length`: 3 |
| billing.address.postcode Zip | ZIP post code | `Necessity`: Optional `Type`: String `Length`: 1-10 |
| billing.address.state | State is used if present. For example, Los Angeles is in CA state. | `Necessity`: Optional `Type`: String `Length`: 2-3 |
| billing.address.street | Street is used for district names and street names. | `Necessity`: Optional `Type`: String `Length`: 1-50 |
| billing.address.street2 | Street 2 is used for long addresses. Usually it contains apartment and building №. | `Necessity`: Optional `Type`: String `Length`: 1-50 |
| billing.phone | Customer’s contact phone number. | `Necessity`: Optional `Type`: String `Length`: 1-20 |
| consumer.birth Day | Сonsumer’s birth day in “ddMMyyyy” format. | `Necessity`: Optional `Type`: String `Length`: 8 |
| consumer.device.imei | Сonsumer’s device international mobile equipment identity. | `Necessity`: Optional `Type`: String `Length`: 14-16 |
| consumer.ip Addresses | Сonsumer’s IP addresses. | `Necessity`: Optional `Type`: List |
| consumer.ip Addresses[] | Сonsumer’s IP address. | `Necessity`: Optional `Type`: String `Length`: 7-15 |
| order | | `Necessity`: Optional `Type`: **Object** |
| order.description | Brief transaction description. May be mandatory for certain Acquirer Banks. | `Necessity`: Optional `Type`: String `Length`: 128 |
| order.site Url | URL of website associated with the transaction. | `Necessity`: Optional `Type`: String `Length`: 128 |
| order.purpose | May be used for better transaction control or additional checks. | `Necessity`: Optional `Type`: String `Length`: 128 |
#### Success Response Parameters
| Parameter Name | Description | Value |
|------------------|------------------------------------------------|------------------------------|
| invoice Id | Verification transaction identifier. | `Type`: String |
| session | | `Type`: **Object** |
| session.token | The session token of verification transaction. | `Type`: String |
#### Fail Response Parameters
| Parameter Name | Description | Value |
|------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------|
| error | | `Type`: **Object** |
| error.cause | Cause of the error. Possible values: `INVALID_REQUEST`, `INVALID_CONFIGURATION`, `INTERNAL_ERROR`, `PROCESSING_FAILED`. | `Type`: Enum |
| error.code | The unique error code. | `Type`: String |
| error.message | Description of the error. | `Type`: String |
| invoice Id | Verification transaction identifier. | `Type`: String |
#### Request Example
```json
{
"billing": {
"address": {
"city": "string",
"country": "string",
"postcodeZip": "string",
"state": "string",
"street": "string",
"street2": "string"
},
"phone": "string"
},
"consumer": {
"birthDay": "string",
"device": {
"imei": "string",
"serialNumber": "string"
},
"email": "string",
"ipAddresses": ["string"]
},
"location": {
"lat": "double",
"lng": "double"
},
"order": {
"description": "string",
"siteUrl": "string",
"purpose": "string"
},
"session": {
"accessToken": "string",
"nonce": "string",
"signature": "string"
},
"sourceCard": {
"expiry": {
"month": "integer",
"year": "integer"
},
"holder":{
"firstName": "string",
"lastName": "string"
},
"number": "string",
"securityCode": "string"
},
"transaction": {
"currency": "string"
}
}
```
#### Success Response Example
```json
{
"invoiceId": "string",
"session": {
"token": "string"
}
}
```
#### Fail Response Example
```json
{
"error": {
"cause": "enum",
"code": "string",
"message": "string"
},
"invoiceId": "string"
}
```
### Sale card mapping notification
#### Introduction
Sale card mapping notification is initiated through HTTPS POST request by using [URLs](#api-url-sale-card-mapping-notification) and the [parameters](#api-parameters-sale-card-mapping-notification).
Card mapping notification is used to allow Consumer credentials (phone, email, billing address, twitter name, etc) for mapping to card data. Card mappings can be used later in transfer or sale transactions instead of card numbers and other cardholder information. Payneteasy sends Sale card mapping notification request to Connecting Party’s server/proxy with created on its side card reference - {server Card Id}.
Connecting Party’s server maps this {server Card Id} to {client Card Id}, created on its side. This {client Card Id} can then be mapped in Connecting Party’s app or on Connecting Party’s server to any Consumer’s data from the initial Perform sale request. This allows Connecting Party’s app to process sale or transfer transactions by Consumer’s email, phone number, etc.
{unique Reference Card Id} remains the same if Consumer makes another transaction with the same card number but different expiry date, for example. It can be used by Connecting Party for loyalty programs or fraud control.
Connecting Party’s app makes new sale requests using {client Card Id} instead of source card data. Payneteasy sends this {client Card Id} to Connecting Party’s server in “Check sale request” and gets mapped to it {server Card Id} in “Check sale response” from Connecting Party’s server, which is used to continue the processing of this transaction.
{server Card Id} of source or verified card can be used for new sale transactions and both as source or destination for new transfer transactions.
#### API URLs
> **Note:** This is an example of URL format on Connecting Party server.
| Connecting Party Server |
|-----------------------------------------------------------|
| https://proxy.connectingpartyserver.com/sale/notification |
#### Request Parameters
| Parameter Name | Description | Value |
|--------------------------------------------|--------------------------------------------------------|---------------------------------------------------------------------------------------------|
| consumer | | `Necessity`: Required `Type`: **Object** |
| consumer.device | | `Necessity`: Required `Type`: **Object** |
| consumer.device.serial Number | Consumer’s device serial number. | `Necessity`: Required `Type`: String `Length`: 1-50 |
| session | | `Necessity`: Required `Type`: **Object** |
| session.access Token | Consumer’s access token key. | `Necessity`: Required `Type`: String `Length`: 32-128 |
| session.token | The session token of sale transaction. | `Necessity`: Required `Type`: String `Length`: 16-36 |
| source Card | | `Necessity`: Optional `Type`: **Object** |
| source Card.bin | The Source card BIN. | `Necessity`: Optional `Type`: Integer |
| source Card.reference | | `Necessity`: Optional `Type`: **Object** |
| source Card.reference.server Card Id | The Source card reference identifier (on server side). | `Necessity`: Optional `Type`: String `Length`: 1-64 |
| source Card.reference.unique Reference Card Id | The Source card unique identifier (on server side). | `Necessity`: Optional `Type`: Integer |
#### Success Response Parameters
| Parameter Name | Description | Value |
|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------|
| invoice Id | Sale transaction identifier. | `Type`: String |
| session | | `Type`: **Object** |
| session.check Signature | Checksum generated by hmac-sha1 (see [Signature computation](https://doc.payneteasy.com/integration/api_development_tools.html.md)) from the concatenation of session.nonce, endpoint Id and invoice Id. | `Type`: String |
| session.nonce | Unique random string generated by Connecting Party’s server. | `Type`: String |
| session.token | The session token of sale transaction. | `Type`: String |
#### Fail Response Parameters
| Parameter Name | Description | Value |
|------------------|------------------------------------------------------------------------------------------------------------|------------------------------|
| error | | `Type`: **Object** |
| error.cause | Сause of the error. Possible values: `FILTERED`, `INVALID_REQUEST`, `SERVER_FAILED`, `SERVER_UNAVAILABLE`. | `Type`: Enum |
| error.code | The unique error code. | `Type`: String |
| error.message | Description of the error. | `Type`: String |
| invoice Id | Sale transaction identifier. | `Type`: String |
#### Request Example
```json
{
"consumer": {
"device": {
"serialNumber": "string"
}
},
"session": {
"accessToken": "string",
"token":"string"
},
"sourceCard": {
"bin": "integer",
"reference": {
"serverCardId": "string",
"uniqueReferenceCardId": "integer"
}
}
}
```
#### Success Response Example
```json
{
"invoiceId": "string",
"session": {
"checkSignature": "string",
"nonce": "string",
"token": "string"
}
}
```
#### Fail Response Example
```json
{
"error": {
"cause": "enum",
"code": "string",
"message": "string"
},
"invoiceId": "string"
}
```
### Sale status
#### Introduction
Sale status is initiated through HTTPS POST request by using [URLs](#api-url-sale-status) and the [parameters](#api-parameters-sale-status).
Sale status request is made by Connecting Party’s app to Payneteasy to get the status of sale transaction.
It is recommended to send Sale status request for a period of 2-3 minutes with interval of 3-5 seconds between requests. Connecting Party’s server should rely on the callback for final status.
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|-----------------------------------------------------------------------------------|--------------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/dapi/v1/sale/{endpoint Id}/{invoice Id}/status | https://gate.payneteasy.eu/paynet/dapi/v1/sale/{endpoint Id}/{invoice Id}/status |
#### Request Parameters
| Parameter Name | Description | Value |
|---------------------|--------------------------------------------------------------------|---------------------------------------------------------|
| session | | `Type`: **Object** |
| session.access Token | The access token key received in Optional consumer authentication. | `Type`: String `Length`: 32-128 |
| session.token | The session token of sale transaction. | `Type`: String `Length`: 16-36 |
#### Success Response Parameters
| Parameter Name | Description | Value |
|------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| invoice Id | Sale transaction identifier. | `Type`: String |
| session | | `Type`: **Object** |
| session.token | The session token of sale transaction | `Type`: String |
| state | Possible values: `PROCESSING`, `REDIRECT_REQUEST`, `APPROVED`, `DECLINED`. | `Type`: Enum |
| bank Order Id | Required if state is `APPROVED` or `DECLINED`. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| redirect Url | Required if state is `REDIRECT_REQUEST`. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| order Id | Order identifier in payment processing system. | `Necessity`: Conditional `Type`: String |
| transaction | | `Necessity`: Conditional `Type`: **Object** |
| transaction.amount Centis | Amount of money transfered in centis, 1.00 EUR = 100 centis. | `Necessity`: Conditional `Type`: Integer |
| transaction.commission Centis | Amount of commission held in centis (depends on the integration). | `Necessity`: Conditional `Type`: Integer |
| transaction.order Created Date | Order creation date in payment processing system. | `Necessity`: Conditional `Type`: String |
| transaction.transaction Created Date | Transaction creation date in payment processing system. | `Necessity`: Conditional `Type`: String |
| error Code | Decline reason code, may present if state is `DECLINED`. | `Necessity`: Optional `Type`: Integer |
| error Message | Decline reason message, may present if state is `DECLINED`. | `Necessity`: Optional `Type`: String `Length`: 128 |
| secure3DAuth Status | Possible values: `AUTHENTICATED`, `NOT_AUTHENTICATED`, `UNSUPPORTED`, `UNSUPPORTED` means that card does not support 3-D Secure or 3DS authentication process finished with an unknown status. | `Necessity`: Optional `Type`: Enum |
| random Sum Auth Status | Possible values: `AUTHENTICATED`, `NOT_AUTHENTICATED`. | `Necessity`: Optional `Type`: Enum |
#### Fail Response Parameters
| Parameter Name | Description | Value |
|------------------|-------------------------------------------------------------------------------------------------------------------------------|------------------------------|
| error | | `Type`: **Object** |
| error.cause | Cause of the error. Possible values: `FILTERED`, `INVALID_REQUEST`, `INTERNAL_ERROR`, `PROCESSING_FAILED`, `ORDER_NOT_FOUND`. | `Type`: Enum |
| error.code | The unique error code. | `Type`: String |
| error.message | Description of the error. | `Type`: String |
| invoice Id | Sale transaction identifier. | `Type`: String |
#### Request Example
```json
{
"session": {
"accessToken": "string",
"token": "string"
}
}
```
#### Success Response Example
```json
{
"bankOrderId": "string",
"invoiceId": "string",
"redirectUrl": "string",
"session": {
"token": "string"
},
"state": "enum"
}
```
#### Fail Response Example
```json
{
"error": {
"cause": "enum",
"code": "string",
"message": "string"
},
"invoiceId": "string"
}
```
### Transfer card mapping notification
#### Introduction
Transfer card mapping notification is initiated through HTTPS POST request by using [URLs](#api-url-transfer-card-mapping-notification) and the [parameters](#api-parameters-transfer-card-mapping-notification).
Card mapping notification is used to allow Consumer credentials (phone, email, billing address, twitter name, etc) for mapping to card data. Card mappings can be used later in transfer or sale transactions instead of card numbers and other cardholder information. Payneteasy sends Transfer card mapping notification request to Connecting Party’s server/proxy with created on its side card reference - {server Card Id}.
Connecting Party’s server maps this {server Card Id} to {client Card Id}, created on its side. This {client Card Id} can then be mapped in Connecting Party’s app or on Connecting Party’s server to any Consumer’s data from the initial Perform transfer request. This allows Connecting Party’s app to process sale or transfer transactions by Consumer’s email, phone number, etc.
{unique Reference Card Id} remains the same if Consumer makes another verification with the same card number but different expiry date, for example. It can be used by Connecting Party for loyalty programs or fraud control.
Connecting Party’s app makes new transfer requests using {client Card Id} instead of source or destination card data. Payneteasy sends this {client Card Id} to Connecting Party’s server in “Check transfer request” and gets mapped to it {server Card Id} in “Check transfer response” from Connecting Party’s server, which is used to continue processing the transfer transaction.
{server Card Id} of source or verified card can be used both as source or destination for new transfer and sale transactions; {server Card Id} of destination card can be used only as destination for new transfers.
#### API URLs
> **Note:** This is an example of URL format on Connecting Party server.
| Connecting Party Server |
|---------------------------------------------------------------|
| https://proxy.connectingpartyserver.com/transfer/notification |
#### Request Parameters
| Parameter Name | Description | Value |
|-------------------------------------------------|-------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| consumer | | `Necessity`: Required `Type`: **Object** |
| consumer.device | | `Necessity`: Required `Type`: **Object** |
| consumer.device.serial Number | Consumer’s device serial number. | `Necessity`: Required `Type`: String `Length`: 1-50 |
| session | | `Necessity`: Required `Type`: **Object** |
| session.access Token | Consumer’s access token key. | `Necessity`: Required `Type`: String `Length`: 32-128 |
| session.token | The session token of transfer transaction. | `Necessity`: Required `Type`: String `Length`: 16-36 |
| destination Card | | `Necessity`: Optional `Type`: **Object** |
| destination Card.bin | The Destination card BIN. | `Necessity`: Optional `Type`: Integer |
| destination Card.reference | | `Necessity`: Optional `Type`: **Object** |
| destination Card.reference.server Card Id | The Destination card reference identifier (on server side). | `Necessity`: Optional `Type`: String `Length`: 1-64 |
| destination Card.reference.unique Reference Card Id | The Destination card unique identifier (on server side). | `Necessity`: Optional `Type`: Integer |
| source Card | | `Necessity`: Optional `Type`: **Object** |
| source Card.bin | The Source card BIN. | `Necessity`: Optional `Type`: Integer |
| source Card.reference | | `Necessity`: Optional `Type`: **Object** |
| source Card.reference.server Card Id | The Source card reference identifier (on server side). | `Necessity`: Optional `Type`: String `Length`: 1-64 |
| source Card.reference.unique Reference Card Id | The Source card unique identifier (on server side). | `Necessity`: Optional `Type`: Integer |
#### Success Response Parameters
| Parameter Name | Description | Value |
|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------|
| invoice Id | Transfer transaction identifier. | `Type`: String |
| session | | `Type`: **Object** |
| session.check Signature | Checksum generated by hmac-sha1 (see [Signature computation](https://doc.payneteasy.com/integration/api_development_tools.html.md)) from the concatenation of session.nonce, endpoint Id and invoice Id. | `Type`: String |
| session.nonce | Unique random string generated by Connecting Party’s server. | `Type`: String |
| session.token | The session token of transfer transaction. | `Type`: String |
#### Fail Response Parameters
| Parameter Name | Description | Value |
|------------------|------------------------------------------------------------------------------------------------------------|------------------------------|
| error | | `Type`: **Object** |
| error.cause | Сause of the error. Possible values: `FILTERED`, `INVALID_REQUEST`, `SERVER_FAILED`, `SERVER_UNAVAILABLE`. | `Type`: Enum |
| error.code | The unique error code. | `Type`: String |
| error.message | Description of the error. | `Type`: String |
| invoice Id | Transfer transaction identifier. | `Type`: String |
#### Request Example
```json
{
"consumer": {
"device": {
"serialNumber": "string"
}
},
"destinationCard": {
"bin": "integer",
"reference": {
"serverCardId": "string",
"uniqueReferenceCardId": "integer"
}
},
"session": {
"accessToken": "string",
"token":"string"
},
"sourceCard": {
"bin": "integer",
"reference": {
"serverCardId": "string",
"uniqueReferenceCardId": "integer"
}
}
}
```
#### Success Response Example
```json
{
"invoiceId": "string",
"session": {
"checkSignature": "string",
"nonce": "string",
"token": "string"
}
}
```
#### Fail Response Example
```json
{
"error": {
"cause": "enum",
"code": "string",
"message": "string"
},
"invoiceId": "string"
}
```
### Transfer status
#### Introduction
Transfer status is initiated through HTTPS POST request by using [URLs](#api-url-transfer-status) and the [parameters](#api-parameters-transfer-status).
Funds transfer status request is made by Connecting Party’s app to Payneteasy to get the status of transfer transaction.
It is recommended to send Transfer status request for a period of 2-3 minutes with interval of 3-5 seconds between requests. Connecting Party’s server should rely on the callback for final status.
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|---------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/dapi/v1/transfer/{endpoint Id}/{invoice Id}/status | https://gate.payneteasy.eu/paynet/dapi/v1/transfer/{endpoint Id}/{invoice Id}/status |
#### Request Parameters
| Parameter Name | Description | Value |
|---------------------|--------------------------------------------------------------------|---------------------------------------------------------|
| session | | `Type`: **Object** |
| session.access Token | The access token key received in Optional consumer authentication. | `Type`: String `Length`: 32-128 |
| session.token | The session token of transfer transaction. | `Type`: String `Length`: 16-36 |
#### Success Response Parameters
| Parameter Name | Description | Value |
|------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| invoice Id | Transfer transaction identifier. | `Type`: String |
| session | | `Type`: **Object** |
| session.token | The session token of transfer transaction. | `Type`: String |
| state | Possible values: `PROCESSING`, `REDIRECT_REQUEST`, `APPROVED`, `DECLINED`. If Consumer defined transfer rates enable get `TRANSFER_FEE_REQUEST`. | `Type`: Enum |
| bank Order Id | Required if state is `APPROVED` or `DECLINED`. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| redirect Url | Required if state is `REDIRECT_REQUEST`. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| order Id | Order identifier in payment processing system. | `Necessity`: Conditional `Type`: String |
| transaction | | `Necessity`: Conditional `Type`: **Object** |
| transaction.amount Centis | Amount of money transfered in centis, 1.00 EUR = 100 centis. | `Necessity`: Conditional `Type`: Integer |
| transaction.commission Centis | Amount of commission held in centis. | `Necessity`: Conditional `Type`: Integer |
| transaction.order Created Date | Order creation date in payment processing system. | `Necessity`: Conditional `Type`: String |
| transaction.transaction Created Date | Transaction creation date in payment processing system. | `Necessity`: Conditional `Type`: String |
| error Code | Decline reason code, may present if state is `DECLINED`. | `Necessity`: Optional `Type`: Integer |
| error Message | Decline reason message, may present if state is `DECLINED`. | `Necessity`: Optional `Type`: String `Length`: 128 |
| secure3DAuth Status | Possible values: `AUTHENTICATED`, `NOT_AUTHENTICATED`, `UNSUPPORTED` means that card does not support 3-D Secure or 3DS authentication process finished with an unknown status. | `Necessity`: Optional `Type`: Enum |
| random Sum Auth Status | Possible values: `AUTHENTICATED`, `NOT_AUTHENTICATED`. | `Necessity`: Optional `Type`: Enum |
#### Success Response Parameters for Consumer defined transfer rates
Transfer status response includes the state parameter with TRANSFER_FEE_REQUEST value and the transfer Fee List object with a list of commissions for possible processing gates. Each processing gate is represented by it’s own aliased name in assigned Id parameter. TRANSFER_FEE_REQUEST value in state parameter exists only in “Consumer defined transfer rates” flow.
When the transaction reaches TRANSFER_FEE_REQUEST state, the processing will remain paused until Complete transfer request is sent.
| Parameter Name | Description | Value |
|----------------------------------|--------------------------------------------------------------------------------------------------------------------------------|------------------------------|
| transfer Fee List | | `Type`: **Object** |
| transfer Fee List.assigned Id | Aliased payment gateway name. | `Type`: String |
| transfer Fee List.commission Centis | Amount of commission to be held in centis, 1.00 EUR = 100 centis. | `Type`: Integer |
| transfer Fee List.currency | Upper case letters (ISO 4217 alpha code). | `Type`: String |
| state | In addition to the values from [Status Transfer](#api-transfer-status), `TRANSFER_FEE_REQUEST` value only exists in this flow. | `Type`: String |
#### Fail Response Parameters
| Parameter Name | Description | Value |
|------------------|-------------------------------------------------------------------------------------------------------------------------------|------------------------------|
| error | | `Type`: **Object** |
| error.cause | Cause of the error. Possible values: `FILTERED`, `INVALID_REQUEST`, `INTERNAL_ERROR`, `PROCESSING_FAILED`, `ORDER_NOT_FOUND`. | `Type`: Enum |
| error.code | The unique error code. | `Type`: String |
| error.message | Description of the error. | `Type`: String |
| invoice Id | Transfer transaction identifier. | `Type`: String |
#### Request Example
```json
{
"session": {
"accessToken": "string",
"token": "string"
}
}
```
#### Success Response Example
```json
{
"bankOrderId": "string",
"invoiceId": "string",
"redirectUrl": "string",
"session": {
"token": "string"
},
"state": "enum"
}
```
#### Success Response Example for Consumer defined transfer rates
**The following structure extends the default Transfer status response body (e.g. 2 processing gates):**
```json
{
"bankOrderId": "string",
"invoiceId": "string",
"redirectUrl": "string",
"session": {
"token": "string"
},
"state": "TRANSFER_FEE_REQUEST",
"transferFeeList": [
{
"assignedId": "string",
"commissionCentis": "integer",
"currency": "string"
},
{
"assignedId": "string",
"commissionCentis": "integer",
"currency": "string"
}
]
}
```
#### Fail Response Example
```json
{
"error": {
"cause": "enum",
"code": "string",
"message": "string"
},
"invoiceId": "string"
}
```
### API Use-Cases
### /api/v2/account-verification-form
#### Introduction
Account Verification form is initiated through HTTPS POST request by using [URLs](#api-url-account-verification-form) and the [parameters](#api-v2-account-verification-form-request-parameters) specified below. Use [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md) for authentication. See [Statuses](https://doc.payneteasy.com/integration/reference/statuses.html.md).
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|---------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v2/account-verification-form/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v2/account-verification-form/ENDPOINTID |
| https://sandbox.payneteasy.eu/paynet/api/v2/account-verification-form/group/ENDPOINTGROUPID | https://gate.payneteasy.eu/paynet/api/v2/account-verification-form/group/ENDPOINTGROUPID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded.
Leading and trailing whitespace in input parameters will be omitted.
Acquirer can redefine the necessity of some fields so they become required instead of optional.
| Request parameter name | Description | Value |
|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| client_orderid | Unique order identifier assigned by Connecting Party. | `Necessity`: Required `Type`: String `Length`: 128 |
| order_desc | Brief order description. | `Necessity`: Required `Type`: String `Length`: 64k |
| address1 | Payer’s address line 1. (Please note that in some cases it is not possible to send address length more than 50 characters. Please contact your manager for more details.) | `Necessity`: Required `Type`: String `Length`: 256 |
| city | Payer’s city. | `Necessity`: Required `Type`: String `Length`: 50 |
| zip_code | Payer’s ZIP code. | `Necessity`: Required `Type`: String `Length`: 10 |
| country | Payer’s country. Please see [Country codes](https://doc.payneteasy.com/integration/reference/country_codes.html.md) for a list of valid country codes. | `Necessity`: Required `Type`: String `Length`: 2 |
| email | Payer’s e-mail address. | `Necessity`: Required `Type`: String `Length`: 50 |
| ipaddress | Payer’s IP address, included for fraud screening purposes. | `Necessity`: Required `Type`: String `Length`: 45 |
| control | Checksum generated by [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md). Control string is represented as concatenation of the following parameters: 1. **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Response Parameters | Description |
|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be async-form-response, validation-error, error etc. If type equals validation-error or error, error-message and error-code parameters contain error details. |
| payet-order-id | Order id assigned to the order by Payneteasy. |
| merchant-order-id | Connecting Party order id. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
| error-message | If status is error this parameter contains the reason for decline or error details. |
| error-code | The error code is case of error status. |
| redirect-url | The URL to the page where the Connecting Party should redirect the Payer’s browser. Connecting Party should send HTTP 302 redirect, see [Account Verification Form Flow](https://doc.payneteasy.com/integration/api_use_cases/account_verification_form.html.md). |
#### Request Example
```http
POST /paynet/api/v2/account-verification-form/39915 HTTP/1.1
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 565
Content-Type: application/x-www-form-urlencoded
Connection: close
client_orderid=34T43R77N
&order_desc=Test Order Description
&first_name=John
&last_name=Smith
&ssn=1267
&birthday=19820115
&address1=100 Main st
&city=Seattle
&state=WA
&zip_code=98102
&country=US
&phone=+12063582043
&cell_phone=+19023384543
&email=john.smith@gmail.com
&ipaddress=65.153.12.232
&site_url=www.google.com
¤cy=USD
&purpose=user_account1
&redirect_url=http://connectingparty.com/result
&server_callback_url=https://httpstat.us/200
&merchant_data=VIP customer
&merchant_form_data=testparam%3Dtest1%26mynewparam%3Dtest2
&control=5112b51084be33fa331d995d17b9d82af3bfbbc9
```
#### Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Wed, 10 May 2023 09:07:27 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 285
type=async-form-response
&serial-number=00000000-0000-0000-0000-000002e378e8
&merchant-order-id=34T43R77N
&paynet-order-id=6998044
&redirect-url=https%3A%2F%2Fsandbox.payneteasy.eu%2Fpaynet%2Fform%2Finit%2FBB587546567A31587163597A684535634A775969614A5538374E4535734B44743364784335716A7979316B673D
```
#### Fail Response Example
```http
HTTP/1.1 200
Server: server
Date: Mon, 22 May 2023 11:36:59 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 152
type=validation-error
&serial-number=00000000-0000-0000-0000-000002e5c587
&merchant-order-id=34T43R77N
&error-message=INVALID_CONTROL_CODE
&error-code=2
```
##### Open API Collection
Open this method in the OpenAPI Reference
View in OpenAPI
### /api/v2/account-verification
#### Introduction
Account Verification is initiated through HTTPS POST request by using [URLs](#api-url-account-verification-url) and the [parameters](#api-url-account-verification-request-parameters) specified below. Use [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md) for authentication. See [Statuses](https://doc.payneteasy.com/integration/reference/statuses.html.md).
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|----------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v2/account-verification/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v2/account-verification/ENDPOINTID |
| https://sandbox.payneteasy.eu/paynet/api/v2/account-verification/group/ENDPOINTGROUPID | https://gate.payneteasy.eu/paynet/api/v2/account-verification/group/ENDPOINTGROUPID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded.
Acquirer can redefine the necessity of some fields so they become required instead of optional.
Leading and trailing whitespace in input parameters will be omitted.
> **Warning:** The following characters must be escaped in the parameter values: & + “.
| Parameter Name | Description | Value |
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| client_orderid | Unique order identifier assigned by Connecting Party. | `Necessity`: Required `Type`: String `Length`: 128 |
| order_desc | Brief order description. | `Necessity`: Required `Type`: String `Length`: 64k |
| address1 | Payer’s address line 1. (Please note that in some cases it is not possible to send address length more than 50 characters. Please contact your manager for more details.) | `Necessity`: Required `Type`: String `Length`: 256 |
| city | Payer’s city. | `Necessity`: Required `Type`: String `Length`: 50 |
| zip_code | Payer’s ZIP code. | `Necessity`: Required `Type`: String `Length`: 10 |
| country | Payer’s country. Please see [Country codes](https://doc.payneteasy.com/integration/reference/country_codes.html.md) for a list of valid country codes. | `Necessity`: Required `Type`: String `Length`: 2 |
| email | Payer’s e-mail address. | `Necessity`: Required `Type`: String `Length`: 50 |
| cvv2 | Payer’s CVV2 code. CVV2 (Card Verification Value) is a three- or four-digit number AFTER the credit card number in the signature area of the card. | `Necessity`: Required `Type`: Numeric `Length`: 3-4 |
| ipaddress | Payer’s IP address, included for fraud screening purposes. | `Necessity`: Required `Type`: String `Length`: 45 |
| control | Checksum generated by [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md). Control string is represented as concatenation of the following parameters: 1. **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Response Parameters | Description |
|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be async-response, validation-error, error etc. If type equals validation-error or error, error-message and error-code parameters contain error details. |
| paynet-order-id | Order id assigned to the order by Payneteasy. |
| merchant-order-id | Connecting Party order id. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
| error-message | If status is error this parameter contains the reason for decline or error details. |
| error-code | The error code is case of error status. |
#### Request Example
```http
POST /paynet/api/v2/account-verification/39915 HTTP/1.1
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 527
Content-Type: application/x-www-form-urlencoded
Connection: close
client_orderid=34T43R77N
&order_desc=Test Order Description
&first_name=John
&last_name=Smith
&birthday=19820115
&address1=100 Main st
&city=Seattle
&state=WA
&zip_code=98102
&country=US
&phone=+12063582043
&cell_phone=+19023384543
&email=john.smith@gmail.com
&ipaddress=65.153.12.232
&site_url=www.google.com
&credit_card_number=4666034752545240
&card_printed_name=CARD HOLDER
&expire_month=12
&expire_year=2099
&cvv2=123
&purpose=user_account1
&server_callback_url=https://httpstat.us/200
&merchant_data=VIP customer
&control=5112b51084be33fa331d995d17b9d82af3bfbbc9
```
#### Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Thu, 27 Apr 2023 14:03:58 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 145
type=async-response
&serial-number=00000000-0000-0000-0000-000002e34518
&merchant-order-id=34T43R77N
&paynet-order-id=6994016
&end-point-id=39915
```
#### Fail Response Example
```http
HTTP/1.1 200
Server: server
Date: Mon, 22 May 2023 11:14:25 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 152
type=validation-error
&serial-number=00000000-0000-0000-0000-000002e5c583
&merchant-order-id=34T43R77N
&error-message=INVALID_CONTROL_CODE
&error-code=2
```
##### Open API Collection
Open this method in the OpenAPI Reference
View in OpenAPI
### /api/v2/documents/add-document
#### Introduction
Add document is initiated through HTTPS POST request by using [URL](#api-url-add-document) and the [parameters](#request-parameters-add-document) specified below. [OAuth HMAC-SHA1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md) is used for authentication (two-legged mode).
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration Base URL | Production Base URL |
|---------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v2/documents/add-document/ENDPOINTID/ORDERID | https://gate.payneteasy.eu/paynet/api/v2/documents/add-document/ENDPOINTID/ORDERID |
#### Request Headers
| Content-Type | The request must contain this header with the following value: binary/octet-stream. |
|----------------|-----------------------------------------------------------------------------------------------------------------------------------------|
| Content-Length | This header specifies correct file size in bytes. |
| Authorization | [OAuth HMAC-SHA1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md) is used for authentication (two-legged mode). |
#### Request Parameters
| Request parameters | Description | Value |
|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| endpoint id | Endpoint of the order. This parameter is passed in request URL. | `Necessity`: Required `Type`: Numeric `Length`: 10 |
| order id | Transaction order identifier assigned by Payment Gateway. This parameter is passed in request URL. | `Necessity`: Required `Type`: String `Length`: 128 |
| consumer key | Connecting Party’s login name. This parameter is used to calculate signature and is passed in Authorization request header as oauth_consumer_key. | `Necessity`: Required `Type`: String `Length`: 20 |
| consumer secret | Connecting Party’s control key. This parameter is used to calculate signature as a part of Encryption key for OAuth HMAC-SHA1. | `Necessity`: Required `Type`: String `Length`: 40 |
| file name | Name of the file to upload, e.g. filename.txt. This parameter is passed in the request body as file and in a query part of request URL as file Name. | `Necessity`: Required `Type`: String `Length`: 255 |
| comment. | Adds a comment to attached file, accessible via pointing cursor on file in order details page. This parameter is passed in a query part of request URL. | `Necessity`: Optional `Type`: String `Length`: 255 |
| file content | Field for the contents of the file. Used to calculate only txt files via bytes per symbol. Use either file content or a combination of file sha1 and file size, not both. Mandatory, if file sha1 and file size fields are empty. This parameter is passed in the request body as a string. | `Necessity`: Conditional `Type`: String `Length`: 255 |
| file sha1 | Calculate sha1 of the file and insert here. Use either file content or a combination of file sha1 and file size, not both. Mandatory, if file content field is empty. This parameter is passed in base part of request URL, after order id parameter. | `Necessity`: Conditional `Type`: String `Length`: 255 |
| file size | Field for file size in bytes. Use either file content or a combination of file sha1 and file size, not both. Mandatory, if file content field is empty. This parameter is passed in Content-Length request header. | `Necessity`: Conditional `Type`: String `Length`: 255 |
#### Response Parameters
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Response Parameters | Description |
|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------|
| status | May have values such as: success or error. Success means that document attached to order successfully. Error provides error-message. |
| error-message | If status is error this parameter contains the reason for decline or error details. |
#### Request Example
```http
POST /paynet/api/v2/documents/add-document/6655/1852755/561d839dde5ae8deeced73c14902e04dc746bfc2?fileName=test5.txt&comment=no%20comments HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Content-Type: binary/octet-stream
Content-Length: 7
Authorization: OAuth realm="",oauth_signature_method="HMAC-SHA1",oauth_signature="ItDxdBQtPRqLiKTAOdy%2BAtDB5cI%3D"
Connection: close
```
#### Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Tue, 18 Jul 2023 06:10:27 GMT
Content-Type: text/plain;charset=utf-8
Content-Length: 14
Connection: close
X-XSS-Protection: 1
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
status=success
```
#### Fail Response Example
```http
HTTP/1.1 200
Server: server
Date: Tue, 18 Jul 2023 07:37:34 GMT
Content-Type: text/plain;charset=utf-8
Content-Length: 46
Connection: close
X-XSS-Protection: 1
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
status=error
&error-message=File+hash+mismatch
```
### /api/v2/auth-cash
#### Introduction
Auth-cash is initiated through HTTPS POST request by using [URLs](#api-v2-auth-cash-url) and the [parameters](#api-v2-auth-cash-request-parameters-url) specified below. Use [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md) for authentication. See [Statuses](https://doc.payneteasy.com/integration/reference/statuses.html.md).
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|------------------------------------------------------------------|---------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v2/auth-cash/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v2/auth-cash/ENDPOINTID |
#### Request Parameters
| Parameter Name | Description | Value |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| client_orderid | Unique order identifier assigned by Connecting Party. | `Necessity`: Required `Type`: String `Length`: 128 |
| order_desc | Brief order description. | `Necessity`: Required `Type`: String `Length`: 64k |
| amount | Amount to be charged. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. | `Necessity`: Required `Type`: Numeric `Length`: 10 |
| currency | Currency the transaction is charged in (See: [Currency codes](https://doc.payneteasy.com/integration/reference/currency_codes.html.md)). Sample values are: USD for US Dollar EUR for European Euro. | `Necessity`: Required `Type`: String `Length`: 3 |
| address1 | Payer’s address line 1. (Please note that in some cases it is not possible to send address length more than 50 characters. Please contact your manager for more details.) | `Necessity`: Required `Type`: String `Length`: 256 |
| city | Payer’s city. | `Necessity`: Required `Type`: String `Length`: 50 |
| zip_code | Payer’s ZIP code. | `Necessity`: Required `Type`: String `Length`: 10 |
| country | Payer’s country. Please see [Country codes](https://doc.payneteasy.com/integration/reference/country_codes.html.md) for a list of valid country codes. | `Necessity`: Required `Type`: String `Length`: 2 |
| phone | Payer’s full international phone number, including country code. | `Necessity`: Required `Type`: String `Length`: 15 |
| email | Payer’s e-mail address. | `Necessity`: Required `Type`: String `Length`: 50 |
| ipaddress | Payer’s IP address, included for fraud screening purposes. | `Necessity`: Required `Type`: String `Length`: 45 |
| control | Checksum generated by [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md). Control string is represented as concatenation of the following parameters: 1. **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Response Parameters | Description |
|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be async-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details. |
| paynet-order-id | Order id assigned to the order by Payneteasy. |
| merchant-order-id | Connecting Party order id. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
| end-point-id | Endpoint id used for the transaction. |
| error-message | If status is error this parameter contains the reason for decline or error details. |
| error-code | The error code is case of error status. |
#### Request Example
```http
POST /paynet/api/v2/auth-cash/46760 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 592
Content-Type: application/x-www-form-urlencoded
Connection: close
client_orderid=inv3982750
&order_desc=Test Order Description
&first_name=John
&last_name=Smith
&ssn=1267
&birthday=19820115
&address1=100 Main st
&city=Seattle&state=WA
&zip_code=98102
&country=US
&phone=+12063582043
&cell_phone=+19023384543
&amount=55
&email=john.smith@gmail.com
¤cy=USD
&ipaddress=65.153.12.232
&site_url=https://doc2.codetime.net
&purpose=user_account1
&redirect_url=http://sandbox.payneteasy.eu/doc/dummy.htm
&server_callback_url=https://httpstat.us/200
&merchant_data=VIP customer
&control=ce2dcc2b307c123242b9867cb0ce15617b8ee7f9
&preferred_language=en
```
#### Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Wed, 14 Jun 2023 08:43:52 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 146
type=async-response
&serial-number=00000000-0000-0000-0000-000002eb1adf
&merchant-order-id=inv3982750
&paynet-order-id=7174243
&end-point-id=46760
```
#### Fail Response Example
```http
HTTP/1.1 200
Server: server
Date: Wed, 14 Jun 2023 08:43:52 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 146
type=validation-error
&serial-number=00000000-0000-0000-0000-000002ddb0d4
&error-message=Project+with+currency+RUB+does+not+apply+request+with+currency+USD
&error-code=16
```
### /api/v2/bank-wire-transfer
#### Introduction
Bank wire transfer is initiated through HTTPS POST request by using [URLs](#api-v2-bank-wire-transfer-request-url) and the [parameters](#api-v2-bank-wire-transfer-request-parameters) specified below. Use [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md) for authentication. See [Statuses](https://doc.payneteasy.com/integration/reference/statuses.html.md).
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|---------------------------------------------------------------------------|------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v2/bank-wire-transfer/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v2/bank-wire-transfer/ENDPOINTID |
#### Request Parameters
| Parameter Name | Description | Value |
|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| client_orderid | Unique order identifier assigned by Connecting Party. | `Necessity`: Required `Type`: String `Length`: 128 |
| currency | Currency the transaction is charged in (See: [Currency codes](https://doc.payneteasy.com/integration/reference/currency_codes.html.md)). Sample values are: USD for US Dollar EUR for European Euro. | `Necessity`: Required `Type`: String `Length`: 3 |
| payer-fullname | Payer’s full name. | `Necessity`: Required `Type`: String `Length`: 128 |
| recipient-account-number | Receiver\`s account number. | `Necessity`: Required `Type`: Numeric `Length`: 20 |
| recipient-bank-bic | Receiver\`s Bank Identifier Code. | `Necessity`: Required `Type`: Numeric `Length`: 9 |
| amount | Amount to be charged. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. | `Necessity`: Required `Type`: Numeric `Length`: 10 |
| payer-email | Payer’s e-mail address. | `Necessity`: Optional `Type`: String `Length`: 128 |
| payer-phone | Payer’s full international phone number, including country code. | `Necessity`: Optional `Type`: String `Length`: 128 |
| recipient-name | Receiver\`s name. | `Necessity`: Required `Type`: String `Length`: 255 |
| recipient-inn | Receiver\`s Taxpayer Identification Number. | `Necessity`: Required `Type`: String `Length`: 255 |
| payment-details | Payment purpose. | `Necessity`: Required `Type`: String `Length`: 120 |
| vat-amount | Value-added tax amount. | `Necessity`: Required `Type`: Numeric `Length`: 10 |
| payer-identity-document | Type, series and number of the identification card. | `Necessity`: Required `Type`: String `Length`: 64 |
| control | Checksum generated by [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md). Control string is represented as concatenation of the following parameters: 1. **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Parameter name | Description |
|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be async-form-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details. |
| paynet-order-id | Order id assigned to the order by Payneteasy. |
| merchant-order-id | Connecting Party order id. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
| error-message | If status is declined or error this parameter contains the reason for decline or error details. |
| error-code | The error code in case of declined or error status. |
#### Request Example
```http
POST /paynet/api/v2/bank-wire-transfer/40265 HTTP/1.1
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 436
Content-Type: application/x-www-form-urlencoded
Connection: close
client_orderid=902B4FF5
&payer-fullname=Test full name
&recipient-name=Test name
&recipient-account-number=40963810202157880527
&recipient-bank-bic=44030861
&amount=55.55
&vat-amount=4.54
¤cy=EUR
&payer-email=john.smith@gmail.com
&payer-phone=+74951129876
&recipient-inn=7812013775
&payment-details=Test payment
&payer-identity-document=01,9207123123
&server_callback_url=https://httpstat.us/200
&control=bc7dae1fe9389aa02471c7c93d08d6b1ba0f2ea8
```
#### Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Fri, 26 May 2023 11:44:12 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 145
type=async-response
&serial-number=00000000-0000-0000-0000-000003c3994f
&merchant-order-id=inv9157586
&paynet-order-id=1824084
&end-point-id=6655
```
#### Fail Response Example
```http
HTTP/1.1 200
Server: server
Date: Fri, 26 May 2023 10:11:58 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 163
type=validation-error
&serial-number=00000000-0000-0000-0000-000002e73881
&merchant-order-id=902B4FF5
&error-message=Project+with+currency+USD+does+not+apply+request+with+currency+EUR
&error-code=20
```
### /api/v2/capture
#### Introduction
Capture is initiated through HTTPS POST request to the [URLs](#api-v2-capture-request-url) and the [parameters](#api-v2-capture-request-parameters) specified below. Use [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md) for authentication. Capture may only be initiated when Preauth have final success status. See [Statuses](https://doc.payneteasy.com/integration/reference/statuses.html.md).
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|---------------------------------------------------------------------------|------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v2/capture/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v2/capture/ENDPOINTID |
| https://sandbox.payneteasy.eu/paynet/api/v2/capture/group/ENDPOINTGROUPID | https://gate.payneteasy.eu/paynet/api/v2/capture/group/ENDPOINTGROUPID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded.
| Request Parameter | Description |
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| login | Connecting Party login name. |
| client_orderid | Connecting Party order identifier of the transaction for which the status is requested. |
| orderid | Order id assigned to the order by Payneteasy |
| currency | Currency the transaction is charged in (See: [Currency codes](https://doc.payneteasy.com/integration/reference/currency_codes.html.md)). Sample values are: USD for US Dollar EUR for European Euro. This parameter may or may not be sent. |
| amount | Amount to be charged. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. This parameter may or may not be sent. |
| control | Checksum generated by [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md). Control string is represented as concatenation of the following parameters: 1. Request parameter: login. 2. Request parameter: merchant-order-id. 3. Request parameter: paynet-order-id. 4. Request parameter: amount in minor units (if sent). 5. request parameter: currency (if amount sent) 6. merchant_control (Control key assigned to Connecting Party account in the Payneteasy gateway system). |
#### Response Parameters
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Response Parameter | Description |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be async-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details. |
| paynet-order-id | Order id assigned to the order by Payneteasy. |
| merchant-order-id | Connecting Party order id. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
| error-message | If status is error this parameter contains the reason for decline or error details. |
| error-code | The error code is case of error status. |
| end-point-id | Endpoint id used for the transaction. |
#### Request Example
```http
POST /paynet/api/v2/capture/39914 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 119
Content-Type: application/x-www-form-urlencoded
Connection: close
login=TestMerchant
&client_orderid=902B4FF5
&orderid=6863088
&amount=345
¤cy=USD
&control=da832c0fcff0105728e26465d5f99e6f83179a45
```
#### Success Response Example
```http
HTTP/1.1 200 OK
Server: server
Date: Mon, 22 Aug 2022 13:15:19 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 140
type=async-response
&serial-number=00000000-0000-0000-0000-000002ddb06a
&merchant-order-id=902B4FF5
&paynet-order-id=6863088
&end-point-id=37211
```
#### Fail Response Example
```http
HTTP/1.1 200 OK
Server: server
Date: Mon, 22 Aug 2022 12:59:09 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 154
pe=validation-error
&serial-number=00000000-0000-0000-0000-000002ddb06b
&error-message=Can+not+make+capture+for+order+state+AUTH_3D_VALIDATING
&error-code=27
```
#### Open API Collection
Open this method in the OpenAPI Reference
View in OpenAPI
### /api/v2/create-card-ref
#### Introduction
Card reference ID creation is initiated through HTTPS POST request by using [URLs](#api-v2-card-ref-id-request-url) and the [parameters](#card-ref-id-request-parameters) specified below. Use [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md) for authentication.
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|-----------------------------------------------------------------------------------|--------------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v2/create-card-ref/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v2/create-card-ref/ENDPOINTID |
| https://sandbox.payneteasy.eu/paynet/api/v2/create-card-ref/group/ENDPOINTGROUPID | https://gate.payneteasy.eu/paynet/api/v2/create-card-ref/group/ENDPOINTGROUPID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded.
| Get Card Ref Request Parameters | Description |
|-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| login | Connecting Party’s login name. |
| client_orderid | Connecting Party’s order identifier of the transaction. |
| orderid | Transaction order identifier assigned by Payment Gateway. |
| control | Checksum generated by [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md). Control string is represented as concatenation of the following parameters: 1. Request parameter: login 2. Request parameter: client_orderid 3. Request parameter: orderid 4. merchant_control (Control key assigned to Connecting Party account in the Payneteasy gateway system). |
Connecting Party has to supply orderid and client_orderid associated with the first payment transaction. It emphasizes that the first payment is a mandatory step to process recurring payments. To authorize the credit card the information about it must be sufficient and an initial payment must be in [final status](https://doc.payneteasy.com/integration/reference/statuses.html.md).
The returned Recurring Payment ID and/or Card Reference ID is a token that refers to cardholder data stored on Payment Gateway side. See the required API command to find which type of token is supported in request parameters. This ID has the following usage:
1. In direct API commands it can be passed instead of cardholder data to initiate new transaction.
2. In form API commands it can be passed to prefill the payment form with previously saved cardholder data.
#### Response Parameters
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Registration Response Parameters | Description |
|------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be async-response, validation-error, error etc. If type equals validation-error or error, error-message and error-code parameters contain error details. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
| card-ref-id | Card reference ID to used in subsequent recurring payments. |
| unq-card-ref-id | Unique card reference ID to each PAN. It can be used by Connecting Party for loyalty programs or fraud control. |
| status | See [Status List](https://doc.payneteasy.com/integration/reference/statuses.html.md) for details. |
| error-message | If status is declined or error this parameter contains the reason for decline. |
| error-code | The error code is case of declined or error status. |
#### Request Example
```http
POST /paynet/api/v2/create-card-ref/46750 HTTP/1.1
Host: https://sandbox.payneteasy.eu
User-Agent: curl/7.85.0
Accept: */*
Content-Length: 100
Content-Type: application/x-www-form-urlencoded
Connection: close
login=login
&client_orderid=902B4FF5
&orderid=6937242
&control=717349cab3fcab2c13c93ff5770ae07a7b8e0727
```
#### Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Tue, 07 Feb 2023 08:46:24 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 144
type=create-card-ref-response
&serial-number=00000000-0000-0000-0000-000002e110a2
&card-ref-id=1461670
&unq-card-ref-id=2463777
&status=approved
```
#### Fail Response Example
```http
HTTP/1.1 200
Server: server
Date: Tue, 07 Feb 2023 08:55:26 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 123
type=validation-error
&serial-number=00000000-0000-0000-0000-000002e110ad
&error-message=INVALID_CONTROL_CODE
&error-code=2
```
#### Open API Collection
Open this method in the OpenAPI Reference
View in OpenAPI
### /api/v2/get-card-info
#### Introduction
For integration purposes use staging environment HTTPS POST request to the [URLs](#api-v2-get-card-info-request-url) and the [parameters](#api-v2-get-card-info-request-parameters) specified below. Use [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md) for authentication. See [Statuses](https://doc.payneteasy.com/integration/reference/statuses.html.md).
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|---------------------------------------------------------------------------------|------------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v2/get-card-info/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v2/get-card-info/ENDPOINTID |
| https://sandbox.payneteasy.eu/paynet/api/v2/get-card-info/group/ENDPOINTGROUPID | https://gate.payneteasy.eu/paynet/api/v2/get-card-info/group/ENDPOINTGROUPID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded.
| Parameter Name | Description | Value |
|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| login | Connecting Party’s login name. | `Necessity`: Mandatory `Type`: String `Length`: 20 |
| cardrefid | Card reference ID obtained at [Card Registration Stage](https://doc.payneteasy.com/integration/api_v2_create-card-ref.html.md). | `Necessity`: Mandatory `Type`: String `Length`: 20 |
| control | Checksum generated by [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md). Control string is represented as concatenation of the following parameters: 1. Request parameter: login 2. Request parameter: cardrefid 3. merchant_control (Control key assigned to Connecting Party account in the Payneteasy gateway system). | `Necessity`: Mandatory `Type`: String `Length`: 128 |
#### Response Parameters
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Information Response Parameters | Description |
|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be get-card-info-response, validation-error, error. If type equals error, error-message and error-code parameters contain error details. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
| card-printed-name | Card holder’s name. |
| bin | Bank Identification Number. |
| last-four-digits | The last four digits of PAN. |
| expire-year | Card expiration year. |
| expire-month | Card expiration month. |
| result-3d | 3DS completion result. |
| error-message | If status is validation-error or error this parameter contains the reason for decline or error details. |
| error-code | The error code is case of validation-error or error status. |
#### Request Example
```http
POST /paynet/api/v2/get-card-info/46750 HTTP/1.1
Host: https://sandbox.payneteasy.eu
User-Agent: curl/7.85.0
Accept: */
Content-Length: 77
Content-Type: application/x-www-form-urlencoded
Connection: close
&login=Test
&cardrefid=1461665
&control=f8ffd7dac9e334799862da0e9190387510d43ff7
```
#### Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Thu, 02 Feb 2023 11:21:39 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 193
type=get-card-info-response
&serial-number=00000000-0000-0000-0000-000002e0d218
&card-printed-name=CARD+HOLDER
&bin=453897
&last-four-digits=6732
&expire-year=2099
&expire-month=12
&result-3d=F
```
#### Fail Response Example
```http
HTTP/1.1 200
Server: server
Date: Thu, 02 Feb 2023 11:26:22 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 136
type=validation-error
&serial-number=00000000-0000-0000-0000-000002e0d21f
&error-message=End+point+with+id+99999+not+found
&error-code=3
```
#### Open API Collection
Open this method in the OpenAPI Reference
View in OpenAPI
### /api/v2/get-exchange
#### Introduction
Get exchange rate is initiated through HTTPS POST request by using [URLs](#api-v2-get-exchange-request-url) and the [parameters](#api-v2-get-exchange-parameters) specified below. Use [OAuth HMAC-SHA1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md) for authentication. See [Statuses](https://doc.payneteasy.com/integration/reference/statuses.html.md).
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|---------------------------------------------------------------------|------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v2/get-exchange/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v2/get-exchange/ENDPOINTID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded and [Authorization headers](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md).
| Parameter Name | Description | Value |
|-----------------------------|------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| exchange-provider | Exchange provider. | `Necessity`: Required `Type`: String `Length`: 128 |
| exchange-currency-code-from | Currency code that need to exchange (See:[Currency codes](https://doc.payneteasy.com/integration/reference/currency_codes.html.md)). | `Necessity`: Required `Type`: String `Length`: 128 |
| exchange-currency-code-to | Currency code that need to get (See:[Currency codes](https://doc.payneteasy.com/integration/reference/currency_codes.html.md)). | `Necessity`: Required `Type`: String `Length`: 128 |
#### Response Parameters
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Parameter Name | Description |
|--------------------|-----------------------|
| exchange-low-rate | Provider’s buy rate. |
| exchange-high-rate | Provider’s sell rate. |
#### Request Example
```http
POST /paynet/api/v2/get-exchange/39790 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth realm="",oauth_version="1.0",oauth_consumer_key="test_merch",oauth_timestamp="1684995901",oauth_nonce="1kKy3hMlAe1",oauth_signature_method="HMAC-SHA1",oauth_signature="jGUaNFqLvBO1gGgWag%2FSU3wMnUc%3D"
Content-Length: 222
Content-Type: application/x-www-form-urlencoded
Connection: close
exchange-currency-code-from=USD
&exchange-currency-code-to=RUB
&exchange-provider=test
&oauth_consumer_key=test_merch
&oauth_nonce=1kKy3hMlAe1
&oauth_signature_method=HMAC-SHA1
&oauth_timestamp=1684995901
&oauth_version=1.0
```
#### Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Thu, 25 May 2023 06:27:46 GMT
Content-Length: 48
Connection: close
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Strict-Transport-Security: max-age=31536000
exchange-low-rate=10.00
&exchange-high-rate=20.00
```
#### Fail Response Example
```http
HTTP/1.1 403
Server: server
Date: Thu, 25 May 2023 07:02:59 GMT
Content-Type: text/html
Content-Length: 735
Connection: close
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
error-message=Book TCurrencyBook was not found by code USB
```
### /api/v2/get-balance
#### Introduction
Get Balance is initiated through HTTPS POST request by using [URLs](#api-v2-get-balance-request-url) and the [parameters](#api-v2-get-balance-request-parameters) specified below. Use [OAuth HMAC-SHA1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md) for authentication. See [Statuses](https://doc.payneteasy.com/integration/reference/statuses.html.md). Also can be viewed on UI. Please contact support managers to enable this feature.
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|--------------------------------------------------------------------|-----------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v2/get-balance/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v2/get-balance/ENDPOINTID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded and [Authorization headers](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md).
| Parameter Name | Description | Value |
|------------------|------------------------------|------------------------------------------------------------------------------------------|
| balance-provider | Input your balance provider. | `Necessity`: Required `Type`: String `Length`: 128 |
#### Response Parameters
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Response Parameters | Description |
|-----------------------|------------------|
| balance-amount | Current balance. |
#### Request Example
```http
POST /paynet/api/v2/get-balance/ HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth realm="",oauth_version="1.0",oauth_consumer_key="balance_test_merchant14",oauth_signature_method="HMAC-SHA1",oauth_signature="hSXMSUPP%2FIGYOOWpU4LVx0mu7SA%3D"
Content-Length: 108
Content-Type: application/x-www-form-urlencoded
Connection: close
balance-provider=Test
&oauth_consumer_key=balance_test_merchant14
&oauth_nonce=2xGTFuAgetE
&oauth_signature_method=HMAC-SHA1
&oauth_timestamp=1686923599
&oauth_version=1.0
```
#### Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Tue, 16 May 2023 08:06:05 GMT
Content-Length: 192
Connection: close
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Strict-Transport-Security: max-age=31536000
[
{
"balance-amount":29.99,
}
]
```
#### Fail Response Example
```http
HTTP/1.1 200
Server: server
Date: Fri, 16 Jun 2023 13:53:43 GMT
Content-Length: 42
Connection: close
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Strict-Transport-Security: max-age=31536000
error-message=Unknown balance provider saa
```
### /api/v2/get-balance/manager
#### Introduction
Get Balance by Manager is initiated through HTTPS POST request by using [URLs](#api-v2-get-balance-manager-request-url) and the [parameters](#api-v2-get-balance-manager-request-parameters) specified below. Use [OAuth HMAC-SHA1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md) for authentication. See [Statuses](https://doc.payneteasy.com/integration/reference/statuses.html.md). Also can be viewed on UI. Please contact technical support to enable this feature.
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|------------------------------------------------------------------------------|---------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v2/get-balance/manager/MANAGERLOGIN | https://gate.payneteasy.eu/paynet/api/v2/get-balance/manager/MANAGERLOGIN |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded and [Authorization headers](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md).
| Parameter Name | Description | Value |
|------------------|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| balance-name | Balance name. If this parameter is omitted, the result will give all available balances. | `Necessity`: Optional `Type`: String `Length`: 128 |
#### Response Parameters
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Response Parameters | Description |
|------------------------------|-------------------------------------------------------------------------------------------------------------|
| name | Balance name. |
| amount | Current balance including STH and Rolling reserve. |
| online-balance-live-amount | Current balance calculated from configuration excluding STH and Rolling reserve. Live = current - STH - RR. |
| total-short-term-hold-amount | Current amount of hold based on Date bumping function. |
| total-rolling-reserve-amount | Current amount calculated from rate plan hold. |
| currency | Currency used for selected balance. |
| merchant Login | Merchant login for the balance. |
| amount-buffer-hold | Calculated amount for OUT operations without final status. |
#### Request Example
```http
POST /paynet/api/v2/get-balance/manager/BalanceTestManager HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth realm="",oauth_version="1.0",oauth_consumer_key="BalanceTestManager",oauth_timestamp="1686924196",oauth_nonce="sT33IbJ4QHs",oauth_signature_method="HMAC-SHA1",oauth_signature="LyKy7M8P%2F%2FZxyLnh7ULW405ODVs%3D"
Content-Length: 156
Content-Type: application/x-www-form-urlencoded
Connection: close
balance-name=saa
&oauth_consumer_key=BalanceTestManager
&oauth_nonce=sT33IbJ4QHs
&oauth_signature_method=HMAC-SHA1
&oauth_timestamp=1686924196
&oauth_version=1.0
```
#### Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Tue, 16 May 2023 08:06:05 GMT
Content-Length: 192
Connection: close
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Strict-Transport-Security: max-age=31536000
[
{
"name":"saa",
"amount":219.500,
"online-balance-live-amount":219.500,
"total-short-term-hold-amount":0.000,
"total-rolling-reserve-amount":0.000,
"currency":"USD",
"merchantLogin":"balance_test_merchant14",
"externalMerchantIdentifier":null,
"amount-buffer-hold":0.000
}
]
```
#### Fail Response Example
```http
HTTP/1.1 403
Server: server
Date: Fri, 16 Jun 2023 13:23:37 GMT
Content-Type: text/html
Content-Length: 735
Connection: close
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
...
Access is denied
```
### /api/v2/get-balance/merchant
#### Introduction
Get Balance by Merchant is initiated through HTTPS POST request by using [URLs](#api-v2-get-balance-merchant-request-url) and the [parameters](#api-v2-get-balance-merchant-request-parameters) specified below. Use [OAuth HMAC-SHA1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md) for authentication. See [Statuses](https://doc.payneteasy.com/integration/reference/statuses.html.md). Also can be viewed on UI. Please contact support managers to enable this feature.
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|--------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v2/get-balance/merchant/MERCHANTLOGIN | https://gate.payneteasy.eu/paynet/api/v2/get-balance/merchant/MERCHANTLOGIN |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded and [Authorization headers](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md).
| Parameter Name | Description | Value |
|------------------|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| balance-name | Balance name. If this parameter is omitted, the result will give all available balances. | `Necessity`: Optional `Type`: String `Length`: 128 |
#### Response Parameters
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Response Parameters | Description |
|------------------------------|--------------------------------------------------------------------------------------------------------------|
| name | Balance name. |
| amount | Current balance including STH and Rolling reserve. |
| online-balance-live-amount | Current balance calculated from configuration excluding STH and Rolling reserve. Live = current - STH - RR.. |
| total-short-term-hold-amount | Current amount of hold based on Date bumping function. |
| total-rolling-reserve-amount | Current amount calculated from rate plan hold. |
| currency | Currency used for selected balance. |
| amount-buffer-hold | Calculated amount for OUT operations without final status. |
#### Request Example
```http
POST /paynet/api/v2/get-balance/merchant/balance_test_merchant14 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth realm="",oauth_version="1.0",oauth_consumer_key="balance_test_merchant14",oauth_timestamp="1686924613",oauth_nonce="qoJPcins4Aw",oauth_signature_method="HMAC-SHA1",oauth_signature="M6fTXbI0tFz4Dy7YEL3SBzCN1I0%3D"
Content-Length: 161
Content-Type: application/x-www-form-urlencoded
Connection: close
balance-name=saa
&oauth_consumer_key=balance_test_merchant14
&oauth_nonce=qoJPcins4Aw
&oauth_signature_method=HMAC-SHA1
&oauth_timestamp=1686924613
&oauth_version=1.0
```
#### Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Tue, 16 May 2023 08:06:05 GMT
Content-Length: 192
Connection: close
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Strict-Transport-Security: max-age=31536000
[
{
"name":"Test1",
"amount":8854.000,
"online-balance-live-amount":8854.000,
"total-short-term-hold-amount":0.000,
"total-rolling-reserve-amount":0.000,
"currency":"AUD",
"amount-buffer-hold":0.000
}
]
```
#### Fail Response Example
```http
HTTP/1.1 200
Server: server
Date: Tue, 16 May 2023 08:06:05 GMT
Content-Length: 192
Connection: close
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Strict-Transport-Security: max-age=31536000
...
Access is denied
```
### /api/v2/make-rebill-preauth
#### Introduction
Preauth recurring transactions are initiated through HTTPS POST request to the [URLs](#make-rebill-request-url) and the [parameters](#make-rebill-request-parameters) specified below. Use [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md) for authentication. See [Statuses](https://doc.payneteasy.com/integration/reference/statuses.html.md).
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|---------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v2/make-rebill-preauth/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v2/make-rebill-preauth/ENDPOINTID |
| https://sandbox.payneteasy.eu/paynet/api/v2/make-rebill-preauth/group/ENDPOINTGROUPID | https://gate.payneteasy.eu/paynet/api/v2/make-rebill-preauth/group/ENDPOINTGROUPID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded.
| Parameter Name | Description | Value |
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| login | Connecting Party’s login name. | `Necessity`: Required `Type`: String `Length`: 20 |
| client_orderid | Connecting Party’s order identifier of the transaction. | `Necessity`: Required `Type`: String `Length`: 128 |
| cardrefid | Card reference ID obtained at Card Registration Stage [/api/v2/create-card-ref/](https://doc.payneteasy.com/integration/api_v2_create-card-ref.html.md). | `Necessity`: Required `Type`: String `Length`: 20 |
| amount | Amount to be charged. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. | `Necessity`: Required `Type`: Numeric `Length`: 10 |
| currency | Currency the transaction is charged in (three-letter currency code). Example of valid parameter values are: USD for US Dollar EUR for European Euro. | `Necessity`: Required `Type`: String `Length`: 3 |
| enumerate_amounts | This parameter may comprise multiple amounts, separated with ,. Payneteasy will cycle through the amounts of the list, try to make a payment on that amount, until there are no more amounts from the list, or not get approved. | `Necessity`: Optional `Type`: String `Length`: 128 |
| recurrent_scenario | Type of the rebill transaction. Possible values: REGULAR or IRREGULAR. If this parameter is sent in the request, it will have priority over the same parameter specified on gate level. Only used for specific acquirers. | `Necessity`: Optional `Type`: String `Length`: 50 |
| recurrent_initiator | Initiator of the rebill transaction. Possible values: CARDHOLDER or MERCHANT. If this parameter is sent in the request, it will have priority over the same parameter specified on gate level. Only used for specific acquirers. | `Necessity`: Optional `Type`: String `Length`: 50 |
| cvv2 | Customer’s CVV2 code. CVV2 (Card Verification Value) is a three- or four-digit number AFTER the credit card number in the signature area of the card. May be empty or absent if bank gateway supports processing without CVV2. | `Necessity`: Optional `Type`: Numeric `Length`: 3-4 |
| ipaddress | Customer’s IP address, included for fraud screening purposes. | `Necessity`: Required `Type`: String `Length`: 45 |
| comment | A short comment. | `Necessity`: Optional `Type`: String `Length`: 50 |
| order_desc | Order description. | `Necessity`: Required `Type`: String `Length`: 64k |
| control | Checksum generated by [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md). Control string is represented as concatenation of the following parameters: 1. Request parameter: login 2. Request parameter: client_orderid 3. Request parameter: cardrefid 4. Request parameter: amount in minor units (if sent). 5. request parameter: currency 6. merchant_control (Control key assigned to Connecting Party account in the Payneteasy gateway system). | `Necessity`: Required `Type`: String `Length`: 40 |
| purpose | Destination to where the payment goes. It is useful for the Connecting Party who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account. Sample values are: +9999999999; mail@example.com etc. This value will be used by fraud monitoring system. | `Necessity`: Optional `Type`: String `Length`: 128 |
| redirect_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved or declined. This parameter should not be used to retrieve results from Payneteasy gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to the backend server_callback_url must be used instead. Parameter is required for 3DS flow and optional for non-3DS. https://doc.payneteasy.com can be used for testing purposes if it’s unknown whether 3DS is used or not. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| server_callback_url | URL, where the transaction status is sent to. Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to server_callback_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of notify_url. If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). | `Necessity`: Optional `Type`: String `Length`: 1024 |
| notify_url | URL, where the transaction status is sent to. Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to notify_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of server_callback_url. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| merchant_data | Any additional information for this transaction which may be useful in Connecting Party’s external systems, e.g. VIP customer, TV promo campaign lead. Will be returned in Status response and Connecting Party Callback. | `Necessity`: Optional `Type`: String `Length`: 64 |
#### Response Parameters
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Sale Response Parameters | Description |
|----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be async-response, validation-error, error etc. If type equals validation-error or error, error-message and error-code parameters contain error details. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
| merchant-order-id | Connecting Party’s order id. |
| paynet-order-id | Order id assigned to the order by Payneteasy. |
| end-point-id | ID of the used End Point. |
| error-message | If status is error this parameter contains the reason for decline or error details. |
| error-code | The error code is case of error status. |
#### Request Example
```http
POST /paynet/api/v2/make-rebill-preauth/46750 HTTP/1.1
Host: https://sandbox.payneteasy.eu
User-Agent: curl/7.85.0
Accept: */
Content-Length: 229
Content-Type: application/x-www-form-urlencoded
Connection: close
&login=login
&client_orderid=902B4FF5
&cardrefid=1461665
&amount=5.00
¤cy=USD
&cvv2=321
&ipaddress=34.129.65.12
&comment=Information abount Rebill
&order_desc=Rebill order description
&control=a37f4972233b4a5dbfb4dcaae149ce7feed01ef9
```
#### Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Thu, 02 Feb 2023 13:10:44 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 144
&type=async-response
&serial-number=00000000-0000-0000-0000-000002e0d498
&merchant-order-id=902B4FF5
&paynet-order-id=6937030
&end-point-id=46750
```
#### Fail Response Example
```http
HTTP/1.1 200
Server: server
Date: Thu, 02 Feb 2023 13:18:50 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 164
type=validation-error
&serial-number=00000000-0000-0000-0000-000002e0d614
&merchant-order-id=902B4FF5
&error-message=End+point+with+id+99999+not+found
&error-code=3
```
### /api/v2/make-rebill-sale
#### Introduction
Recurring transactions are initiated through HTTPS POST request to the [URLs](#api-v2-make-rebill-request-url) and the [parameters](#api-v2-make-rebill-request-parameters) specified below. Use [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md) for authentication. See [Statuses](https://doc.payneteasy.com/integration/reference/statuses.html.md).
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|------------------------------------------------------------------------------------|---------------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v2/make-rebill-sale/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v2/make-rebill-sale/ENDPOINTID |
| https://sandbox.payneteasy.eu/paynet/api/v2/make-rebill-sale/group/ENDPOINTGROUPID | https://gate.payneteasy.eu/paynet/api/v2/make-rebill-sale/group/ENDPOINTGROUPID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded.
| Parameter Name | Description | Value |
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| login | Connecting Party’s login name. | `Necessity`: Required `Type`: String `Length`: 20 |
| client_orderid | Connecting Party’s order identifier of the transaction. | `Necessity`: Required `Type`: String `Length`: 128 |
| cardrefid | Card reference ID obtained at Card Registration Stage [/api/v2/create-card-ref/](https://doc.payneteasy.com/integration/api_v2_create-card-ref.html.md). | `Necessity`: Required `Type`: String `Length`: 20 |
| amount | Amount to be charged. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. | `Necessity`: Required `Type`: Numeric `Length`: 10 |
| currency | Currency the transaction is charged in (three-letter currency code). Example of valid parameter values are: USD for US Dollar EUR for European Euro. | `Necessity`: Required `Type`: String `Length`: 3 |
| enumerate_amounts | This parameter may comprise multiple amounts, separated with ,. Payneteasy will cycle through the amounts of the list, try to make a payment on that amount, until there are no more amounts from the list, or not get approved. | `Necessity`: Optional `Type`: String `Length`: 128 |
| recurrent_scenario | Type of the rebill transaction. Possible values: REGULAR or IRREGULAR. If this parameter is sent in the request, it will have priority over the same parameter specified on gate level. Only used for specific acquirers. | `Necessity`: Optional `Type`: String `Length`: 50 |
| recurrent_initiator | Initiator of the rebill transaction. Possible values: CARDHOLDER or MERCHANT. If this parameter is sent in the request, it will have priority over the same parameter specified on gate level. Only used for specific acquirers. | `Necessity`: Optional `Type`: String `Length`: 50 |
| cvv2 | Customer’s CVV2 code. CVV2 (Card Verification Value) is a three- or four-digit number AFTER the credit card number in the signature area of the card. May be empty or absent if bank gateway supports processing without CVV2. | `Necessity`: Optional `Type`: Numeric `Length`: 3-4 |
| ipaddress | Customer’s IP address, included for fraud screening purposes. | `Necessity`: Required `Type`: String `Length`: 45 |
| comment | A short comment. | `Necessity`: Optional `Type`: String `Length`: 50 |
| order_desc | Order description. | `Necessity`: Required `Type`: String `Length`: 64k |
| control | Checksum generated by [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md). Control string is represented as concatenation of the following parameters: 1. Request parameter: login 2. Request parameter: client_orderid 3. Request parameter: cardrefid 4. Request parameter: amount in minor units (if sent). 5. request parameter: currency 6. merchant_control (Control key assigned to Connecting Party account in the Payneteasy gateway system). | `Necessity`: Required `Type`: String `Length`: 40 |
| purpose | Destination to where the payment goes. It is useful for the Connecting Party who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account. Sample values are: +9999999999; mail@example.com etc. This value will be used by fraud monitoring system. | `Necessity`: Optional `Type`: String `Length`: 128 |
| redirect_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved or declined. This parameter should not be used to retrieve results from Payneteasy gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to the backend server_callback_url must be used instead. Parameter is required for 3DS flow and optional for non-3DS. https://doc.payneteasy.com can be used for testing purposes if it’s unknown whether 3DS is used or not. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| server_callback_url | URL, where the transaction status is sent to. Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to server_callback_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of notify_url. If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). | `Necessity`: Optional `Type`: String `Length`: 1024 |
| notify_url | URL, where the transaction status is sent to. Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to notify_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of server_callback_url. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| merchant_data | Any additional information for this transaction which may be useful in Connecting Party’s external systems, e.g. VIP customer, TV promo campaign lead. Will be returned in Status response and Connecting Party Callback. | `Necessity`: Optional `Type`: String `Length`: 64 |
#### Response Parameters
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Sale Response Parameters | Description |
|----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be async-response, validation-error, error etc. If type equals validation-error or error, error-message and error-code parameters contain error details. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
| merchant-order-id | Connecting Party’s order ID. |
| paynet-order-id | Order id assigned to the order by Payneteasy. |
| end-point-id | ID of the used End Point. |
| error-message | If status is error this parameter contains the reason for decline or error details. |
| error-code | The error code is case of error status. |
#### Request Example
```http
POST /paynet/api/v2/make-rebill-sale/46750 HTTP/1.1
Host: https://sandbox.payneteasy.eu
User-Agent: curl/7.85.0
Accept: */
Content-Length: 229
Content-Type: application/x-www-form-urlencoded
Connection: close
&login=login
&client_orderid=902B4FF5
&cardrefid=1461665
&amount=5.00
¤cy=USD
&cvv2=123
&ipaddress=34.129.65.12
&comment=Information abount Rebill
&order_desc=Rebill order description
&control=a37f4972233b4a5dbfb4dcaae149ce7feed01ef9
```
#### Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Thu, 02 Feb 2023 13:22:04 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 144
type=async-response
&serial-number=00000000-0000-0000-0000-000002e0d6b9
&merchant-order-id=902B4FF5
&paynet-order-id=6937242
&end-point-id=46750
```
#### Fail Response Example
```http
HTTP/1.1 200
Server: server
Date: Thu, 02 Feb 2023 13:24:47 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 164
type=validation-error
&serial-number=00000000-0000-0000-0000-000002e0d74c
&merchant-order-id=902B4FF5
&error-message=End+point+with+id+99999+not+found
&error-code=3
```
### /api/v2/pan-eligibility/form
#### Introduction
PAN Eligibility form is initiated through HTTPS POST request by using [URLs](#api-v2-pan-eligibility-form-request-url) and the [parameters](#api-v2-pan-eligibility-form-request-parameters) specified below. Use [OAuth HMAC-SHA1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md) for authentication. See [Statuses](https://doc.payneteasy.com/integration/reference/statuses.html.md).
#### PAN Eligibility API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Method | Integration | Production |
|----------------|-------------------------------------------------------------------------------------|----------------------------------------------------------------------------------|
| Sending-only | https://sandbox.payneteasy.eu/paynet/api/v2/pan-eligibility/send-form/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v2/pan-eligibility/send-form/ENDPOINTID |
| Receiving-only | https://sandbox.payneteasy.eu/paynet/api/v2/pan-eligibility/receive-form/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v2/pan-eligibility/receive-form/ENDPOINTID |
| Both | https://sandbox.payneteasy.eu/paynet/api/v2/pan-eligibility/both-form/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v2/pan-eligibility/both-form/ENDPOINTID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded and [Authorization headers](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md).
| Parameter Name | Description | Value |
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| client_orderid | Unique order identifier assigned by Connecting Party. | `Necessity`: Required `Type`: String `Length`: 128 |
| redirect_url | URL, where the Payer is redirected to upon completion of the transaction. Please note that redirection is performed in any case, no matter whether transaction is approved, declined in any other final [status](https://doc.payneteasy.com/integration/reference/statuses.html.md). Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize server_callback_url or [status API command](https://doc.payneteasy.com/integration/api_v2_status.html.md). Pass https://doc.payneteasy.com if you have no need to return payer anywhere. Use either redirect_url or combination of redirect_success_url and redirect_fail_url, not both. | `Necessity`: Optional `Type`: String `Length`: 128 |
| server_callback_url | URL, where the transaction status is sent to. Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to server_callback_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of notify_url. If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). | `Necessity`: Optional `Type`: String `Length`: 128 |
| notify_url | URL, where the transaction status is sent to. Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to notify_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of server_callback_url. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. | `Necessity`: Optional `Type`: String `Length`: 128 |
#### Response Parameters
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Response Parameters | Description |
|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be async-response, validation-error, error etc. If type equals validation-error or error, error-message and error-code parameters contain error details. |
| paynet-order-id | Order id assigned to the order by Payneteasy. |
| merchant-order-id | Connecting Party order id. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
| error-message | If status is error this parameter contains the reason for decline or error details. |
| error-code | The error code is case of error status. |
#### Send-form Request Example
```http
POST /paynet/api/v2/pan-eligibility/send-form/39907 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth realm="",oauth_version="1.0",oauth_consumer_key="javid_test_merch",oauth_timestamp="1687507473",oauth_nonce="Gs2vcwIXv6H",oauth_signature_method="HMAC-SHA1",oauth_signature="sMQWXIUY0OTgBzt2OavSFhT3Q3s%3D"
Content-Length: 192
Content-Type: application/x-www-form-urlencoded
Connection: close
client-order-id=1234567890
&oauth_consumer_key=test_merch
&oauth_nonce=Gs2vcwIXv6H
&oauth_signature_method=HMAC-SHA1
&oauth_timestamp=1687507473
&oauth_version=1.0
&redirect-url=http%3A%2F%2Fsandbox.payneteasy.eu%2Fdoc%2Fdummy.htm
```
#### Send-form Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Wed, 21 Jun 2023 11:19:20 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 147
type=async-response
&serial-number=00000000-0000-0000-0000-000002ec863e
&merchant-order-id=1234567890
&paynet-order-id=7211136
&redirect-url=https%3A%2F%2Fsandbox.payneteasy.eu%2Fpaynet%2Fform%2Fpan-eligibility%2Finit%2FBB3757784F4A53585143535A554E2F4D6A3264715A616E744C6C31667043414962654534575039376E636F343D
```
#### Send-form Fail Response Example
```http
HTTP/1.1 200 OK
Server: server
Date: Mon, 22 Aug 2022 12:59:09 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 154
...
Access is denied
```
#### Receive-form Request Example
```http
POST /paynet/api/v2/pan-eligibility/receive-form/39907 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth realm="",oauth_version="1.0",oauth_consumer_key="javid_test_merch",oauth_timestamp="1687511712",oauth_nonce="cRmRev3FdaP",oauth_signature_method="HMAC-SHA1",oauth_signature="6zWG0Sli0dehdFikhoGdoEqhcQA%3D"
Content-Length: 226
Content-Type: application/x-www-form-urlencoded
Connection: close
client-order-id=1234567890
&oauth_consumer_key=test_merch
&oauth_nonce=cRmRev3FdaP
&oauth_signature_method=HMAC-SHA1
&oauth_timestamp=1687511712
&oauth_version=1.0
&redirect-url=http%3A%2F%2Fsandbox.payneteasy.eu%2Fdoc%2Fdummy.htm
```
#### Receive-form Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Wed, 21 Jun 2023 12:19:20 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 147
type=async-response
&serial-number=00000000-0000-0000-0000-000002ec863e
&merchant-order-id=1234567890
&paynet-order-id=7211136
&redirect-url=https%3A%2F%2Fsandbox.payneteasy.eu%2Fpaynet%2Fform%2Fpan-eligibility%2Finit%2FBB3757784F4A53585143535A554E2F4D6A3264715A616E744C6C316670434149626545436159574254497A4D3D
```
#### Receive-form Fail Response Example
```http
HTTP/1.1 200 OK
Server: server
Date: Mon, 22 Aug 2022 12:59:09 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 154
...
Access is denied
```
#### Both-form Request Example
```http
POST /paynet/api/v2/pan-eligibility/both-form/39907 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth realm="",oauth_version="1.0",oauth_consumer_key="javid_test_merch",oauth_timestamp="1687512444",oauth_nonce="Nu8SL8l70H2",oauth_signature_method="HMAC-SHA1",oauth_signature="wypHgzYjxmKrdshhj1CabwPGnnA%3D"
Content-Length: 226
Content-Type: application/x-www-form-urlencoded
Connection: close
client-order-id=1234567890
&oauth_consumer_key=test_merch
&oauth_nonce=Gs2vcwIXv6H
&oauth_signature_method=HMAC-SHA1
&oauth_timestamp=1687507765
&oauth_version=1.0
&redirect-url=http%3A%2F%2Fsandbox.payneteasy.eu%2Fdoc%2Fdummy.htm
```
#### Both-form Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Wed, 21 Jun 2023 13:19:20 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 147
type=async-response
&serial-number=00000000-0000-0000-0000-000002ec863e
&merchant-order-id=1234567890
&paynet-order-id=7211136
&redirect-url=https%3A%2F%2Fsandbox.payneteasy.eu%2Fpaynet%2Fform%2Fpan-eligibility%2Finit%2FBB3757784F4A53585143535A554E2F4D6A3264715A616E744C6C31667043414962654534575039376E636F343D
```
#### Both-form Fail Response Example
```http
HTTP/1.1 200 OK
Server: server
Date: Mon, 22 Aug 2022 13:19:09 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 154
...
Access is denied
```
### /api/v2/pan-eligibility
#### Introduction
PAN Eligibility is initiated through HTTPS POST request by using [URLs](#api-v2-pan-eligibility-request-url) and the [parameters](#api-v2-pan-eligibility-request-parameters) specified below. Use [OAuth HMAC-SHA1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md) for authentication. See [Statuses](https://doc.payneteasy.com/integration/reference/statuses.html.md).
#### PAN Eligibility API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Method | Integration | Production |
|----------------|--------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| Sending-only | https://sandbox.payneteasy.eu/paynet/api/v2/pan-eligibility/send/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v2/pan-eligibility/send/ENDPOINTID |
| Receiving-only | https://sandbox.payneteasy.eu/paynet/api/v2/pan-eligibility/receive/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v2/pan-eligibility/receive/ENDPOINTID |
| Both | https://sandbox.payneteasy.eu/paynet/api/v2/pan-eligibility/both/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v2/pan-eligibility/both/ENDPOINTID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded and [Authorization headers](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md).
Sending-only
| Parameter | Description | Value |
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| client_orderid | Connecting Party order ID. | `Necessity`: Required `Type`: String `Length`: 128 |
| sending-card-number | Sender\`s credit card number. (if sending-card-ref-id is not specified) | `Necessity`: Required `Type`: Numeric `Length`: 19 |
| card-printed-name | Sender\`s card printed name. (if sending-card-ref-id is not specified) | `Necessity`: Required `Type`: String `Length`: 128 |
| expire-month | Sender credit card’s month of expiration. (if sending-card-ref-id is not specified) | `Necessity`: Required `Type`: Numeric `Length`: 2 |
| expire-year | Sender credit card’s year of expiration. (if sending-card-ref-id is not specified) | `Necessity`: Required `Type`: Numeric `Length`: 4 |
| sending-card-ref-id | Sender\`s card ref ID. (if sending-card-number is not specified) | `Necessity`: Required `Type`: Numeric `Length`: 20 |
| server_callback_url | URL, where the transaction status is sent to. Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to server_callback_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of notify_url. If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). | `Necessity`: Optional `Type`: String `Length`: 1024 |
| notify_url | URL, where the transaction status is sent to. Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to notify_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of server_callback_url. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. | `Necessity`: Optional `Type`: String `Length`: 1024 |
Receiving-only
| Parameter | Description | Value |
|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| client_orderid | Connecting Party order ID. | `Necessity`: Required `Type`: String `Length`: 128 |
| receiving-card-number | Receiver\`s credit card number. (if receiving-card-ref-id is not specified) | `Necessity`: Required `Type`: Numeric `Length`: 19 |
| receiving-card-ref-id | Receiver\`s card ref ID. (if receiving-card-number is not specified) | `Necessity`: Required `Type`: Numeric `Length`: |
| server_callback_url | URL, where the transaction status is sent to. Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to server_callback_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of notify_url. If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). | `Necessity`: Optional `Type`: String `Length`: 1024 |
| notify_url | URL, where the transaction status is sent to. Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to notify_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of server_callback_url. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. | `Necessity`: Optional `Type`: String `Length`: 1024 |
Both
| Parameter | Description | Value |
|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| client_orderid | Connecting Party order ID. | `Necessity`: Required `Type`: String `Length`: 128 |
| sending-card-number | Sender\`s card number. (if sending-card-ref-id is not specified) | `Necessity`: Required `Type`: Numeric `Length`: 19 |
| card-printed-name | Sender\`s card printed name. (if sending-card-ref-id is not specified) | `Necessity`: Required `Type`: String `Length`: 128 |
| expire-month | Sender credit card’s month of expiration. (if sending-card-ref-id is not specified) | `Necessity`: Required `Type`: Numeric `Length`: 2 |
| expire-year | Sender credit card’s year of expiration. (if sending-card-ref-id is not specified) | `Necessity`: Required `Type`: Numeric `Length`: 4 |
| sending-card-ref-id | Sender\`s card ref ID. (if sending-card-ref-id is not specified) | `Necessity`: Required `Type`: Numeric `Length`: 20 |
| receiving-card-number | Receiver\`s card number. (if receiving-card-ref-id is not specified) | `Necessity`: Required `Type`: Numeric `Length`: 19 |
| receiving-card-ref-id | Receiver\`s card ref ID. (if receiving-card-number is not specified) | `Necessity`: Required `Type`: Numeric `Length`: |
| server_callback_url | URL, where the transaction status is sent to. Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to server_callback_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of notify_url. If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). | `Necessity`: Optional `Type`: String `Length`: 1024 |
| notify_url | URL, where the transaction status is sent to. Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to notify_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of server_callback_url. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. | `Necessity`: Optional `Type`: String `Length`: 1024 |
#### Response Parameters
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Response Parameters | Description |
|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be async-response, validation-error, error etc. If type equals validation-error or error, error-message and error-code parameters contain error details. |
| paynet-order-id | Order id assigned to the order by Payneteasy. |
| merchant-order-id | Connecting Party order id. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
| error-message | If status is error this parameter contains the reason for decline or error details. |
| error-code | The error code is case of error status. |
#### Send Request Example
```http
POST /paynet/api/v2/pan-eligibility/send/39907 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth realm="",oauth_version="1.0",oauth_consumer_key="test_merch",oauth_timestamp="1687507082",oauth_nonce="XQkXQgLxhCE",oauth_signature_method="HMAC-SHA1",oauth_signature="lLTiOEyUY%2FwibmGVA%2F5rY6qIS9I%3D"
Content-Length: 192
Content-Type: application/x-www-form-urlencoded
Connection: close
client_orderid=1234567890
&oauth_consumer_key=test_merch
&oauth_nonce=XQkXQgLxhCE
&oauth_signature_method=HMAC-SHA1
&oauth_timestamp=1687507082
&oauth_version=1.0
&sending-card-ref-id=1461790
```
#### Send Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Wed, 21 Jun 2023 11:19:20 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 147
type=async-response
&serial-number=00000000-0000-0000-0000-000002ecbcba
&merchant-order-id=1234567890
&paynet-order-id=7216063
&end-point-id=39907
```
#### Send Fail Response Example
```http
HTTP/1.1 200 OK
Server: server
Date: Mon, 22 Aug 2022 11:19:20 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 154
...
Access is denied
```
#### Receive Request Example
```http
POST /paynet/api/v2/pan-eligibility/receive/39907 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth realm="",oauth_version="1.0",oauth_consumer_key="test_merch",oauth_timestamp="1687507082",oauth_nonce="XQkXQgLxhCE",oauth_signature_method="HMAC-SHA1",oauth_signature="lLTiOEyUY%2FwibmGVA%2F5rY6qIS9I%3D"
Content-Length: 192
Content-Type: application/x-www-form-urlencoded
Connection: close
client_orderid=1234567890
&oauth_consumer_key=test_merch
&oauth_nonce=XQkXQgLxhCE
&oauth_signature_method=HMAC-SHA1
&oauth_timestamp=1687507082
&oauth_version=1.0
&receiving-card-number=4444555566661111
```
#### Receive Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Wed, 21 Jun 2023 12:19:20 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 147
type=async-response
&serial-number=00000000-0000-0000-0000-000002ecbcba
&merchant-order-id=1234567890
&paynet-order-id=7216063
&end-point-id=39907
```
#### Receive Fail Response Example
```http
HTTP/1.1 200 OK
Server: server
Date: Mon, 22 Aug 2022 12:19:29 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 154
...
Access is denied
```
#### Both Request Example
```http
POST /paynet/api/v2/pan-eligibility/both/39907 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth realm="",oauth_version="1.0",oauth_consumer_key="test_merch",oauth_timestamp="1687513856",oauth_nonce="T0z9qml2rDZ",oauth_signature_method="HMAC-SHA1",oauth_signature="rsHewN7TRIxzPQAtd99z5eoSyJY%3D"
Content-Length: 231
Content-Type: application/x-www-form-urlencoded
Connection: close
client_orderid=1234567890
&oauth_consumer_key=test_merch
&oauth_nonce=T0z9qml2rDZ
&oauth_signature_method=HMAC-SHA1
&oauth_timestamp=1687513856
&oauth_version=1.0
&receiving-card-number=4444555566661111
&sending-card-ref-id=1461790
```
#### Both Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Fri, 23 Jun 2023 09:51:15 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 146
type=async-response
&serial-number=00000000-0000-0000-0000-000002ecbcc2
&merchant-order-id=1234567890
&paynet-order-id=7216068
&end-point-id=39907
```
#### Both Fail Response Example
```http
HTTP/1.1 200 OK
Server: server
Date: Mon, 22 Aug 2022 13:19:29 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 154
...
Access is denied
```
### /api/v2/payout-form
#### Introduction
Payout-form is initiated through HTTPS POST request by using [URLs](#api-v2-payout-form-url) and the [parameters](#api-v2-payout-form-parameters) specified below. Use [OAuth HMAC-SHA1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md) for authentication. See [Statuses](https://doc.payneteasy.com/integration/reference/statuses.html.md).
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|---------------------------------------------------------------------------------|----------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v2/payout-form/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v2/payout-form/ENDPOINTID |
| https://sandbox.payneteasy.eu/paynet/api/v2/payout-form/group/ENDPOINTIDGROUPID | https://gate.payneteasy.eu/paynet/api/v2/payout-form/group/ENDPOINTGROUPID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded and [Authorization headers](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md).
Ask support manager if conditional fields are required for integration.
| Parameter Name | Description | Value |
|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
| client_orderid | Connecting Party’s order identifier. | `Necessity`: Required `Type`: String `Lenght`: 128 |
| amount | Amount to be charged. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. | `Necessity`: Required `Type`: Numeric `Lenght`: 10 |
| currency | Currency the transaction is charged in (three-letter currency code). Sample values are: USD for US Dollar EUR for European Euro. | `Necessity`: Required `Type`: String `Length`: 3 |
| order_desc | Brief order description. | `Necessity`: Required `Type`: String `Length`: 65K |
| ipaddress | Receiver’s IP address (IPv4 or IPv6). | `Necessity`: Conditional `Type`: String `Length`: 7-45 |
| purpose | Payout purpose. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| server_callback_url | URL, where the transaction status is sent to. Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to server_callback_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of notify_url. If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). | `Necessity`: Optional `Type`: String `Length`: 1024 |
| notify_url | URL, where the transaction status is sent to. Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to notify_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of server_callback_url. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| redirect_url | URL, where the Receiver is redirected to upon completion of the transaction. Please note that redirection is performed in any case, no matter whether transaction is approved, declined in any other final [status](https://doc.payneteasy.com/integration/reference/statuses.html.md). Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize server_callback_url or [status API command](https://doc.payneteasy.com/integration/api_v2_status.html.md). Pass https://doc.payneteasy.com if you have no need to return Receiver anywhere. Use either redirect_url or combination of redirect_success_url and redirect_fail_url, not both. | `Necessity`: Required if both redirect_success_url and redirect_fail_url are missing `Type`: String `Length`: 1024 |
| redirect_success_url | URL, where the Receiver is redirected to when transaction status is approved (See [status list](https://doc.payneteasy.com/integration/reference/statuses.html.md)). Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize server_callback_url or [status API command](https://doc.payneteasy.com/integration/api_v2_status.html.md). Otherwise put https://doc.payneteasy.com if there is no need to redirect Receiver anywhere. Use either combination of redirect_success_url and redirect_fail_url or redirect_url, not both. | `Necessity`: Required if redirect_url parameter is missing `Type`: String `Lenght`: 1024 |
| redirect_fail_url | URL, where the Receiver is redirected to when transaction status is not approved (See [status list](https://doc.payneteasy.com/integration/reference/statuses.html.md)). Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize server_callback_url or [status API command](https://doc.payneteasy.com/integration/api_v2_status.html.md). Pass https://doc.payneteasy.com if you use non-3DS schema for transactions processing and you have no need to return Receiver anywhere. Use either combination of redirect_fail_url and redirect_success_url or redirect_url, not both. | `Necessity`: Required if redirect_url parameter is missing `Type`: String `Length`: 1024 |
| account_number | Account number. | `Necessity`: Conditional `Type`: String `Length`: 32 |
| account_name | Bank account. | `Necessity`: Conditional `Type`: String `Length`: 512 |
| ewallet_wallet | E-wallet ID. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| crypto_wallet_address | Address of crypto wallet. | `Necessity`: Conditional `Type`: String `Length`: 64 |
| bank_name | Bank Name. | `Necessity`: Conditional `Type`: String `Length`: 512 |
| bank_branch | Bank Branch Name. | `Necessity`: Conditional `Type`: String `Length`: 512 |
| bank_code | Bank code. | `Necessity`: Conditional `Type`: String `Length`: 32 |
| bank_address1 | Bank address. | `Necessity`: Conditional `Type`: String `Length`: 255 |
| bank_zip_code | Bank postal ZIP code. | `Necessity`: Conditional `Type`: String `Length`: 32 |
| bank_province | Bank province. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| bank_area | Bank area. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| bank_city | Bank city. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| routing_number | Routing number used to identify specific bank branches in China. | `Necessity`: Conditional `Type`: String `Length`: 32 |
| legal_person_name | Name on the legal document. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| legal_person_document_number | Number of legal document. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| receiver_first_name | Receiver first name, also can be sent as first_name. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| receiver_last_name | Receiver last name, also can be sent as last_name. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| receiver_birthday | Receiver birthday, also can be sent as birthday. | `Necessity`: Conditional `Type`: Numeric `Length`: 30 |
| receiver_country_code | Receiver country code, also can be sent as country. | `Necessity`: Conditional `Type`: String `Length`: 3 |
| receiver_state | Receiver state, should be provided for countries that have states (USA, Canada, Australia), also can be sent as state. | `Necessity`: Conditional `Type`: String `Length`: 4 |
| receiver_city | Receiver city, also can be sent as city. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| receiver_zip_code | Receiver zip code, also can be sent as zip_code. | `Necessity`: Conditional `Type`: Numeric `Length`: 32 |
| receiver_address1 | Receiver address, also can be sent as address1. | `Necessity`: Conditional `Type`: String `Length`: 255 |
| receiver_phone | Receiver phone, also can be sent as phone. | `Necessity`: Conditional `Type`: Numeric `Length`: 128 |
| receiver_email | Receiver E-mail, also can be sent as email. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| receiver_identity_document_id | Receiver identity document identifier, also can be sent as identity_document_id. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| receiver_identity_document_number | Receiver identity document number, also can be sent as identity_document_number. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| merchant_data | Any additional information for this transaction which may be useful in Connecting Party’s external systems, e.g. VIP customer, TV promo campaign lead. Will be returned in Status response and Connecting Party’s Callback. | `Necessity`: Optional `Type`: String `Length`: 65k |
| merchant_form_data | Parameters sent in merchant_form_data API parameter are parsed into macros with the same name, the parameter is url-encoded, example: testparam%3Dtest1%26mynewparam%3Dtest2 and is parsed into $MFD_testparam = test1 and $MFD_mynewparam = test2 macros in the form. Parameter name characters[a-zA-Z0-9], parameter value characters[a-zA-Z0-9], only characters = and & are allowed as control characters, 2MB max size. For example, this parameter can be used to display payment form in light/dark mode depending on the value passed by Connecting Party (e.g. pass merchant_form_data=theme%3Ddark in request and $MFD_theme macro placeholder on payment form will be changed to dark. | `Necessity`: Optional `Type`: String `Length`: 2M |
| preferred_language | Preferred language. | `Necessity`: Optional `Type`: String `Length`: 2 |
#### Response Parameters
> **Note:** Response has a Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Parameter Name | Description |
|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be async-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details. |
| paynet-order-id | Order id assigned to the order by Payneteasy. |
| merchant-order-id | Connecting Party order id. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
| error-message | If status is error this parameter contains the reason for decline or error details. |
| error-code | The error code is case of error status. |
| redirect_url | The URL to the page where the Connecting Party should redirect the client’s browser. Connecting Party should send HTTP 302 redirect. |
#### Request Example
```http
POST /paynet/api/v2/payout-form/39529 HTTP/1.1
Host: sandbox.doc2.com
User-Agent: curl/8.12.1
Accept: */*
Authorization: OAuth realm="",oauth_version="1.0",oauth_consumer_key="merchantlogin",oauth_timestamp="1753337681",oauth_nonce="T5v7kcMBsgi",oauth_signature_method="HMAC-SHA1",oauth_signature="wTTQQiN%2F2bGjfCTcSAQ3ZhAHMLw%3D"
Content-Length: 249
Content-Type: application/x-www-form-urlencoded
Connection: keep-alive
account_number=1234567890
&order_desc=Test_Order_Description
&amount=100
&bank_branch=test_branch
&bank_name=test_bank
&client_orderid=12345
¤cy=USD
&oauth_consumer_key=merchantlogin
&oauth_nonce=T5v7kcMBsgi
&oauth_signature_method=HMAC-SHA1
&oauth_timestamp=1753337681
&oauth_version=1.0
```
#### Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Thu, 24 Jul 2025 06:45:56 GMT
Content-Type: text/html;charset=utf-8
Connection: keep-alive
Keep-Alive: timeout=60
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 142
type=async-response
&serial-number=00000000-0000-0000-0000-000002f3b45d
&merchant-order-id=12345
&paynet-order-id=7366391
&end-point-id=132490
```
#### Fail Response Example
```http
HTTP/1.1 403
Server: server
Date: Thu, 24 Jul 2025 06:26:23 GMT
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Connection: keep-alive
Keep-Alive: timeout=60
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Length: 102
type=error
&serial-number=00000000-0000-0000-0000-000002f3b456
&error-message=Forbidden
&error-code=-1
```
#### Test Scenario
Different Payout transaction statuses can be received on sandbox, depending on the account_number value passed in Payout request.
Testing account_number values:
> * account_number = 1234567890 to get APPROVED
> * account_number = 0987654321 to get DECLINED
> * account_number = 1987654321 to get PROCESSOR_INTERNAL_ERROR
#### Open API Collection
Open this method in the OpenAPI Reference
View in OpenAPI
### /api/v2/preauth-form
#### Introduction
Preauth-form is initiated through HTTPS POST request by using [URLs](#api-v2-preauth-form-url) and the [parameters](#api-v2-preauth-form-request-parameters) specified below. Use [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md) for authentication. See [Statuses](https://doc.payneteasy.com/integration/reference/statuses.html.md).
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|--------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v2/preauth-form/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v2/preauth-form/ENDPOINTID |
| https://sandbox.payneteasy.eu/paynet/api/v2/preauth-form/group/ENDPOINTGROUPID | https://gate.payneteasy.eu/paynet/api/v2/preauth-form/group/ENDPOINTGROUPID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded.
Acquirer can redefine the necessity of some fields so they become required instead of optional.
Leading and trailing whitespace in input parameters will be omitted.
| Parameter Name | Description | Value |
|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| client_orderid | Unique order identifier assigned by Connecting Party. | `Necessity`: Required `Type`: String `Length`: 128 |
| order_desc | Brief order description. | `Necessity`: Required `Type`: String `Length`: 64k |
| amount | Amount to be charged. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. | `Necessity`: Required `Type`: Numeric `Length`: 10 |
| currency | Currency the transaction is charged in (See: [Currency codes](https://doc.payneteasy.com/integration/reference/currency_codes.html.md)). Sample values are: USD for US Dollar EUR for European Euro. | `Necessity`: Required `Type`: String `Length`: 3 |
| address1 | Payer’s address line 1. (Please note that in some cases it is not possible to send address length more than 50 characters. Please contact your manager for more details.) | `Necessity`: Required `Type`: String `Length`: 256 |
| city | Payer’s city. | `Necessity`: Required `Type`: String `Length`: 50 |
| zip_code | Payer’s ZIP code. | `Necessity`: Required `Type`: String `Length`: 10 |
| country | Payer’s country. Please see [Country codes](https://doc.payneteasy.com/integration/reference/country_codes.html.md) for a list of valid country codes. | `Necessity`: Required `Type`: String `Length`: 2 |
| phone | Payer’s full international phone number, including country code. | `Necessity`: Required `Type`: String `Length`: 15 |
| email | Payer’s e-mail address. | `Necessity`: Required `Type`: String `Length`: 50 |
| ipaddress | Payer’s IP address, included for fraud screening purposes. | `Necessity`: Required `Type`: String `Length`: 45 |
| control | Checksum generated by [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md). Control string is represented as concatenation of the following parameters: 1. **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Response Parameters | Description |
|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be async-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details. |
| paynet-order-id | Order id assigned to the order by Payneteasy. |
| merchant-order-id | Connecting Party order id. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
| error-message | If status is error this parameter contains the reason for decline or error details. |
| error-code | The error code is case of error status. |
| redirect-url | The URL to the page where the Connecting Party should redirect the client’s browser. Connecting Party should send HTTP 302 redirect, see [General Payment-form Process Flow](https://doc.payneteasy.com/integration/api_use_cases/sale_form.html.md). |
#### Request Example
```http
POST /paynet/api/v2/preauth-form/39539 HTTP/1.1
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 314
Content-Type: application/x-www-form-urlencoded
Connection: close
client_orderid=902B4FF5
&order_desc=Test Order Description
&first_name=John
&last_name=Smith
&ssn=1267&birthday=19820115
&address1=100 Main st
&city=Seattle
&state=WA
&zip_code=98102
&country=US
&phone=+12063582043
&cell_phone=+19023384543
&amount=69
&email=john.smith@gmail.com
¤cy=USD
&ipaddress=65.153.12.232
&site_url=https://doc.payneteasy.com
&credit_card_number=4538977399606732
&card_printed_name=CARD HOLDER
&expire_month=12
&expire_year=2099
&cvv2=123
&purpose=user_account1
&redirect_url=http://sandbox.payneteasy.eu/doc/dummy.htm
&server_callback_url=https://httpstat.us/200
&merchant_data=VIP customer
&merchant_form_data=testparam%3Dtest1%26mynewparam%3Dtest2
&control=b7ba0b0ce36fda192c3772e045520c7a9cb5e442
&preferred_language=en
```
#### Success Response Example
```http
HTTP/1.1 200 OK
Server: server
Date: Thu, 13 Oct 2022 09:54:53 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 280
type=async-form-response
&serial-number=00000000-0000-0000-0000-000002ddb0d3
&merchant-order-id=Test
&paynet-order-id=6863103
&redirect-url=https%3A%2F%2Fsandbox.payneteasy.eu%2Fpaynet%2Fform%2Finit%2FBB587546567A31587163597A68633370432F78675258396E6F78367975715973596936522B594B4F646168553D
```
#### Fail Response Example
```http
HTTP/1.1 200 OK
Server: server
Date: Thu, 13 Oct 2022 09:58:28 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 170
type=validation-error
&serial-number=00000000-0000-0000-0000-000002ddb0d4
&error-message=Project+with+currency+RUB+does+not+apply+request+with+currency+USD
&error-code=16
```
#### Open API Collection
Open this method in the OpenAPI Reference
View in OpenAPI
### /api/v2/preauth
#### Introduction
Preauth is initiated through HTTPS POST request by using [URLs](#api-v2-preauth-request-url) and the [parameters](#api-v2-preauth-request-parameters-url) specified below. Use [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md) for authentication. See [Statuses](https://doc.payneteasy.com/integration/reference/statuses.html.md).
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|---------------------------------------------------------------------------|------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v2/preauth/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v2/preauth/ENDPOINTID |
| https://sandbox.payneteasy.eu/paynet/api/v2/preauth/group/ENDPOINTGROUPID | https://gate.payneteasy.eu/paynet/api/v2/preauth/group/ENDPOINTGROUPID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded.
| Parameter Name | Description | Value |
|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| client_orderid | Unique order identifier assigned by Connecting Party. | `Necessity`: Required `Type`: String `Length`: 128 |
| order_desc | Brief order description. | `Necessity`: Required `Type`: String `Length`: 125 |
| amount | Amount to be charged. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. | `Necessity`: Required `Type`: Numeric `Length`: 10 |
| currency | Currency the transaction is charged in (See: [Currency codes](https://doc.payneteasy.com/integration/reference/currency_codes.html.md)). Sample values are: USD for US Dollar EUR for European Euro. | `Necessity`: Required `Type`: String `Length`: 3 |
| address1 | Payer’s address line 1. (Please note that in some cases it is not possible to send address length more than 50 characters. Please contact your manager for more details.) | `Necessity`: Required `Type`: String `Length`: 256 |
| city | Payer’s city. | `Necessity`: Required `Type`: String `Length`: 50 |
| zip_code | Payer’s ZIP code. | `Necessity`: Required `Type`: String `Length`: 10 |
| country | Payer’s country. Please see [Country codes](https://doc.payneteasy.com/integration/reference/country_codes.html.md) for a list of valid country codes. | `Necessity`: Required `Type`: String `Length`: 2 |
| phone | Payer’s full international phone number, including country code. | `Necessity`: Required `Type`: String `Length`: 15 |
| email | Payer’s e-mail address. | `Necessity`: Required `Type`: String `Length`: 50 |
| ipaddress | Payer’s IP address, included for fraud screening purposes. | `Necessity`: Required `Type`: String `Length`: 45 |
| control | Checksum generated by [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md). Control string is represented as concatenation of the following parameters: 1. **Note:** Browser data for 3DS 2. X is gathered by Payneteasy system on 3DS authentication stage. For some processing channels, however, the browser data and/or Connecting Party URL for 3DS challenge results must be provided in initial transaction request. Please contact Support manager to clarify if these parameters should be included in request parameters.
The Connecting Party’s site needs to accurately populate the browser information for each transaction. This data can be obtained by Connecting Party’s servers. Ensure that the data is not altered or hard-coded, and that it is unique to each transaction.
| Parameter Name | Description | Value |
|----------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| ipaddress | IP address of the browser as returned by the HTTP headers to the 3DS Requestor. | `Necessity`: Required `Type`: String `Length`: 45 |
| customer_browser_accept_header | Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser. | `Necessity`: Required `Type`: String `Length`: 2048 |
| customer_browser_javascript_enabled | Boolean that represents the ability of the cardholder browser to execute Java Script. | `Necessity`: Required `Type`: Boolean `Length`: - |
| customer_browser_accept_language | Value representing the browser language as defined in IETF BCP47. | `Necessity`: Required `Type`: String `Length`: 8 |
| customer_browser_user_agent | Exact content of the HTTP user-agent header. | `Necessity`: Required `Type`: String `Length`: 2048 |
| tds_areq_notification_url, alias tds_cres_notification_url | Fully qualified URL of Connecting Party system that will receive the CRes message or Error Message. This CRes message must be sent to Payneteasy. See details here [Upload CRes Result](https://doc.payneteasy.com/integration/upload-cres-result.html.md). | `Necessity`: Optional `Type`: String `Length`: 256 |
| customer_browser_info | If true, then the fields below must be present. | `Necessity`: Optional `Type`: Boolean `Length`: - |
| customer_browser_color_depth | Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Becomes required when browser_java Script_enabled = true. | `Necessity`: Optional `Type`: String `Length`: 2 |
| customer_browser_java_enabled | Boolean that represents the ability of the cardholder browser to execute Java. Becomes required when browser_java Script_enabled = true. | `Necessity`: Optional `Type`: Boolean `Length`: - |
| customer_browser_screen_height | Total height of the Cardholder’s screen in pixels. Becomes required when browser_java Script_enabled = true. | `Necessity`: Optional `Type`: Numeric `Length`: 6 |
| customer_browser_screen_width | Total width of the cardholder’s screen in pixels. Becomes required when browser_java Script_enabled = true. | `Necessity`: Optional `Type`: Numeric `Length`: 6 |
| customer_browser_time_zone | Time-zone offset in minutes between UTC and the Cardholder browser local time. Note that the offset is positive if the local time zone is behind UTC and negative if it is ahead. Becomes required when browser_java Script_enabled = true. | `Necessity`: Optional `Type`: String `Length`: 5 |
##### For Payment Institutions
The PSP or Acquirer can fill the 3DS results for each transaction, if 3DS authentication is performed on their side.
| Parameter Name | Description | Value |
|------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------|
| tds_authentication_result_type | Type of result. Possible values are: - SIMPLE | `Type`: String `Length`: 6 |
| tds_authentication_result_authentication_type | Authentication Type. Indicates the type of authentication method the Issuer will use to challenge the Cardholder, whether in the ARes message or what was used by the ACS when in the RReq message. Possible values are: - 01 = Static - 02 = Dynamic - 03 = OOB - 04 = Decoupled - 05-79 = Reserved for EMVCo future use (values invalid until defined by EMVCo) - 80-99 = Reserved for DS use | `Type`: String `Length`: 2 |
| tds_authentication_result_authentication_value | Authentication Value. Payment System-specific value provided by the ACS or the DS using an algorithm defined by Payment System. Authentication Value may be used to provide proof of authentication. A 20-byte value that has been Base64 encoded, giving a 28-byte result | `Type`: String `Length`: 19-28 |
| tds_authentication_result_transaction_id | xid for 1.0.2 or ds TransID for 2.1.0/2.2.0 | `Type`: String `Length`: 19-36 |
| tds_authentication_result_transaction_status | Transaction Status. Indicates whether a transaction qualifies as an authenticated transaction or account verification. Possible values are: - Y = Authentication Verification Successful - N = Not Authenticated/Account Not Verified, Transaction denied - U = Authentication/Account Verification Could Not Be Performed, Technical or other problem, as indicated in ARes or RReq - A = Attempts Processing Performed, Not Authenticated/Verified, but a proof of attempted authentication/verification is provided - C = Challenge Required, Additional authentication is required using the CReq/CRes - D = Challenge Required, Decoupled Authentication confirmed - R = Authentication/ Account Verification Rejected, Issuer is rejecting | `Type`: String `Length`: 1 |
| tds_authentication_result_message_version | Message Version Number. Protocol version identifier This shall be the Protocol Version Number of the specification utilised by the system creating this message. The Message Version Number is set by the 3DS Server which originates the protocol with the AReq message. The Message Version Number does not change during a 3DS transaction. Possible values are: - 1.0.2 - 2.1.0 - 2.2.0 | `Type`: String `Length`: 5 |
#### Response Parameters
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Response Parameters | Description |
|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be async-response, validation-error, error etc. If type equals validation-error or error, error-message and error-code parameters contain error details. |
| paynet-order-id | Order id assigned to the order by Payneteasy. |
| merchant-order-id | Connecting Party order id. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
| error-message | If status is error this parameter contains the reason for decline or error details. |
| error-code | The error code is case of error status. |
| end-point-id | Endpoint id used for the transaction. |
#### Request with Cardholder Data Example
```http
POST /paynet/api/v2/preauth/39549 HTTP/1.1
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 314
Content-Type: application/x-www-form-urlencoded
Connection: close
credit_card_number=4538977399606732
&card_printed_name=CARD HOLDER
&expire_month=12
&expire_year=2099
&cvv2=123
&client_orderid=902B4FF5
&order_desc=Test Order Description
&first_name=John
&last_name=Smith
&ssn=1267
&birthday=19820115
&address1=100 Main st
&city=Seattle
&state=WA
&zip_code=98102
&country=US
&phone=%2B12063582043
&cell_phone=%2B19023384543
&email=john.smith@gmail.com
¤cy=USD
&amount=10.42
&ipaddress=65.153.12.232
&site_url=https://doc.payneteasy.com
&purpose=user_account1
&redirect_url=https://doc.payneteasy.com/doc/dummy.htm
&server_callback_url=https://httpstat.us/200
&merchant_data=VIP customer
&control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483
```
#### Request with Card Recurring Payment ID Example
```http
POST /paynet/api/v2/preauth/39549 HTTP/1.1
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 314
Content-Type: application/x-www-form-urlencoded
Connection: close
card_recurring_payment_id=1491927
&cvv2=123
&client_orderid=34T43R77N
&order_desc=Test Order Description
&amount=777
¤cy=USD
&ipaddress=65.153.12.232
&redirect_url=https://doc.payneteasy.com/doc/dummy.htm
&server_callback_url=https://httpstat.us/200
&control=218d377897ce25c2ac69d99de42bc6902eb5bcd8
```
#### Success Response Example
```http
HTTP/1.1 200 OK
Server: server
Date: Mon, 05 Sep 2022 10:43:57 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 139
type=async-response
&serial-number=00000000-0000-0000-0000-000002ddb018
&merchant-order-id=123
&paynet-order-id=6863073
&end-point-id=39914
```
#### Fail Response Example
```http
HTTP/1.1 200 OK
Server: server
Date: Mon, 05 Sep 2022 10:51:14 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 208
type=validation-error
&serial-number=00000000-0000-0000-0000-000002ddb019
&merchant-order-id=123
&error-message=Validate+card+number+failed.+Card+Number+length+must+be+between+16+and+19+digits..
&error-code=8
```
#### Open API Collection
Open this method in the OpenAPI Reference
View in OpenAPI
### /api/v2/return
#### Introduction
Return transactions may only be initiated when the transaction have final successful status. See [Statuses](https://doc.payneteasy.com/integration/reference/statuses.html.md). For Preauth it makes Cancel transaction, for Capture and Sale – Reversal. Return transactions are initiated through HTTPS POST request by using [URLs](#api-v2-return-request-url) and the [parameters](#api-v2-return-request-parameters-url) specified below. Use [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md) for authentication.
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|--------------------------------------------------------------------------|-----------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v2/return/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v2/return/ENDPOINTID |
| https://sandbox.payneteasy.eu/paynet/api/v2/return/group/ENDPOINTGROUPID | https://gate.payneteasy.eu/paynet/api/v2/return/group/ENDPOINTGROUPID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded.
> **Warning:** The following characters must be escaped in the parameter values: & + “.
| Parameter Name | Description | Value |
|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| login | Connecting Party login name. | `Necessity`: Mandatory `Type`: String `Length`: 20 |
| orderid | Unique order identifier assigned by Payneteasy system. | `Necessity`: Mandatory `Type`: String `Length`: 20 |
| client_orderid | Unique Connecting Party identifier. | `Necessity`: Mandatory `Type`: String `Length`: 128 |
| control | Checksum generated by [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md). Control string is represented as concatenation of the following parameters: 1. Request parameter: login. 2. Request parameter: client_orderid. 3. Request parameter: orderid. 4. Request parameter: amount (in minor units, if sent). 5. Request parameter: currency (if sent). 6. merchant_control (Control key assigned to Connecting Party account in the Payneteasy gateway system). | `Necessity`: Conditional `Type`: String `Length`: 128 |
| amount | The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. If this parameter is omitted, initial transaction is reversed as a whole. Amount only makes sense for reversals, not cancels. Amount cannot exceed initial transaction amount. Please note that Currency MUST be specified if amount is specified! | `Necessity`: Mandatory `Type`: Numeric `Length`: 10 |
| currency | Currency in which amount is specified. Provided in three-letter currency code format. Example: USD for US Dollar. Reference: [Currency Codes](https://doc.payneteasy.com/integration/reference/currency_codes.html.md). | `Necessity`: Mandatory `Type`: String `Length`: 50 |
| comment | A brief description of reason. | `Necessity`: Mandatory `Type`: String `Length`: 50 |
#### Response Parameters
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Parameter Name | Description |
|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be async-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details. |
| paynet-order-id | Order id assigned to the order by Payneteasy. |
| merchant-order-id | Connecting Party order id. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
| end-point-id | Entry point used for processing this transaction. |
| error-message | If status is error this parameter contains the reason for decline or error details. |
| error-code | The error code is case of error status. |
#### Request Example
```http
POST /paynet/api/v2/return/39914 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 162
Content-Type: application/x-www-form-urlencoded
Connection: close
login=TestMerchant
&client_orderid=Test
&orderid=6862958
&amount=5.00
¤cy=RUB
&comment=Service not provided
&control=2dfdb99c4eff5b31c978ecb8bc4b4d094e24c1d4
```
#### Success Response Example
```http
HTTP/1.1 200 OK
Server: server
Date: Mon, 08 Aug 2022 07:50:08 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 141
type=async-response
&serial-number=00000000-0000-0000-0000-000002ddad4a
&merchant-order-id=Test
&paynet-order-id=6862958
&end-point-id=39914
```
#### Fail Response Example
```http
HTTP/1.1 200 OK
Server: server
Date: Mon, 08 Aug 2022 10:45:32 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 153
type=validation-error
&serial-number=00000000-0000-0000-0000-000002ddad5c
&error-message=Reversal+currency+does+not+match+project+currency
&error-code=16
```
#### Open API Collection
Open this method in the OpenAPI Reference
View in OpenAPI
### /api/v2/sale-echeck
#### Introduction
Sale-e Check is initiated through HTTPS POST request by using [URLs](#api-v2-echeck-request-url) and the [parameters](#api-v2-echeck-request-parameters) specified below. Use [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md) for authentication. See [Statuses](https://doc.payneteasy.com/integration/reference/statuses.html.md).
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|--------------------------------------------------------------------|-----------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v2/sale-echeck/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v2/sale-echeck/ENDPOINTID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded.
Leading and trailing whitespace in input parameters will be omitted.
| Parameter Name | Description | Value |
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| client_orderid | Unique order identifier assigned by Connecting Party. | `Necessity`: Required `Type`: String `Length`: 128 |
| order_desc | Brief order description. | `Necessity`: Required `Type`: String `Length`: 64k |
| first_name | Payer’s first name. Parameter necessity depends on the Acquiring channel and necessity of it must be clarified with Tech Support. | `Necessity`: Required `Type`: String `Length`: 50 |
| last_name | Payer’s last name. Parameter necessity depends on the Acquiring channel and necessity of it must be clarified with Tech Support. | `Necessity`: Required `Type`: String `Length`: 50 |
| ssn | Last four digits of the Payer’s social security number. | `Necessity`: Optional `Type`: Numeric `Length`: 32 |
| birthday | Payer’s date of birth, in the format YYYYMMDD. | `Necessity`: Optional `Type`: Numeric `Length`: 8 |
| address1 | Payer’s address line 1. (Please note that in some cases it is not possible to send address length more than 50 characters. Please contact your manager for more details.) | `Necessity`: Required `Type`: String `Length`: 256 |
| city | Payer’s city. | `Necessity`: Required `Type`: String `Length`: 50 |
| state | Payer’s state. Please see [Mandatory State codes](https://doc.payneteasy.com/integration/reference/country_codes.html.md) for a list of valid state codes. Required for USA, Canada and Australia. | `Necessity`: Conditional `Type`: String `Length`: 2-3 |
| zip_code | Payer’s ZIP code. | `Necessity`: Required `Type`: String `Length`: 10 |
| country | Payer’s country. Please see [Country codes](https://doc.payneteasy.com/integration/reference/country_codes.html.md) for a list of valid country codes. | `Necessity`: Required `Type`: String `Length`: 2 |
| phone | Payer’s full international phone number, including country code. | `Necessity`: Required `Type`: String `Length`: 15 |
| email | Payer’s e-mail address. | `Necessity`: Required `Type`: String `Length`: 50 |
| amount | Amount to be charged. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. | `Necessity`: Required `Type`: Numeric `Length`: 10 |
| currency | Currency the transaction is charged in (See: [Currency codes](https://doc.payneteasy.com/integration/reference/currency_codes.html.md)). Sample values are: USD for US Dollar EUR for European Euro. | `Necessity`: Required `Type`: String `Length`: 3 |
| routing_number | This element should contain the Payer’s 9 digit bank routing number. | `Necessity`: Required `Type`: String `Length`: 9 |
| account_number | This element should contain the Payer’s bank account number. | `Necessity`: Required `Type`: String `Length`: 20 |
| check_number | This element should contain the Payer’s check number. | `Necessity`: Optional `Type`: String `Length`: 22 |
| check_date | This element should contain the Payer’s check date. Format is MM/DD/YYYY. | `Necessity`: Optional `Type`: String `Length`: 12 |
| bank_name | This element should contain the Payer’s bank name. | `Necessity`: Optional `Type`: String `Length`: 12 |
| ipaddress | Payer’s IP address, included for fraud screening purposes. | `Necessity`: Required `Type`: String `Length`: 45 |
| control | Checksum generated by [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md). Control string is represented as concatenation of the following parameters: 1. **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Response Parameters | Description |
|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be async-response, validation-error, error etc. If type equals validation-error or error, error-message and error-code parameters contain error details. |
| status | See [Status List](https://doc.payneteasy.com/integration/reference/statuses.html.md) for details. |
| paynet-order-id | Order id assigned to the order by Payneteasy. |
| merchant-order-id | Connecting Party order id. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
| error-message | If status is error this parameter contains the reason for decline or error details. |
| error-code | The error code is case of error status. |
#### Request Example
```http
POST /paynet/api/v2/sale-echeck/39790 HTTP/1.1
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 314
Content-Type: application/x-www-form-urlencoded
Connection: close
client_orderid=902B4FF5
&order_desc=Test Order Description
&first_name=John
&last_name=Smith
&ssn=1267
&birthday=19820115
&address1=100 Main st
&city=Seattle
&state=WA
&zip_code=98102
&country=US
&phone=+12063582043
&amount=10.55
&email=john.smith@gmail.com
¤cy=USD
&ipaddress=65.153.12.232
&routing_number=113024588
&account_number=1234567890
&check_number=77778888
&check_date=02/22/2025
&bank_name=testbank
&server_callback_url=https%3A%2F%2Fhttpstat.us%2F200
&control=5ce2641b344bf35930ba9536055d24f038a1065b
```
#### Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Wed, 26 Apr 2023 13:51:16 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 144
type=async-response
&serial-number=00000000-0000-0000-0000-000002e3450d
&merchant-order-id=902B4FF5
&paynet-order-id=6994012
&end-point-id=39790
```
#### Fail Response Example
```http
HTTP/1.1 200
Server: server
Date: Wed, 26 Apr 2023 13:51:16 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 144
type=validation-error
&serial-number=00000000-0000-0000-0000-000002b36f64
&merchant-order-id=inv4097763
&error-message=End+point+with+id+39790+not+found
&error-code=3
```
### /api/v2/sale-form
#### Introduction
Sale-form is initiated through HTTPS POST request by using [URLs](#api-v2-sale-form-url) and the [parameters](#api-v2-sale-form-request-parameters) specified below. Use [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md) for authentication. See [Statuses](https://doc.payneteasy.com/integration/reference/statuses.html.md).
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|-----------------------------------------------------------------------------|--------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v2/sale-form/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v2/sale-form/ENDPOINTID |
| https://sandbox.payneteasy.eu/paynet/api/v2/sale-form/group/ENDPOINTGROUPID | https://gate.payneteasy.eu/paynet/api/v2/sale-form/group/ENDPOINTGROUPID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded.
Acquirer can redefine the necessity of some fields so they become required instead of optional.
Leading and trailing whitespace in input parameters will be omitted.
> **Warning:** The following characters must be escaped in the parameter values: & + “.
| Parameter Name | Description | Value |
|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| client_orderid | Unique order identifier assigned by Connecting Party. | `Necessity`: Required `Type`: String `Length`: 128 |
| order_desc | Brief order description. | `Necessity`: Required `Type`: String `Length`: 64k |
| first_name | Payer’s first name. Parameter necessity depends on the Acquiring channel and necessity of it must be clarified with Tech Support. | `Necessity`: Required `Type`: String `Length`: 50 |
| last_name | Payer’s last name. Parameter necessity depends on the Acquiring channel and necessity of it must be clarified with Tech Support. | `Necessity`: Required `Type`: String `Length`: 50 |
| ssn | Last four digits of the payer’s social security number. | `Necessity`: Optional `Type`: Numeric `Length`: 32 |
| birthday | Payer’s date of birth, in the format YYYYMMDD. | `Necessity`: Optional `Type`: Numeric `Length`: 8 |
| address1 | Payer’s address line 1. (Please note that in some cases it is not possible to send address length more than 50 characters. Please contact your manager for more details.) | `Necessity`: Required `Type`: String `Length`: 256 |
| city | Payer’s city. | `Necessity`: Required `Type`: String `Length`: 50 |
| state | Payer’s state. Please see [Mandatory State codes](https://doc.payneteasy.com/integration/reference/country_codes.html.md) for a list of valid state codes. Required for USA, Canada and Australia. | `Necessity`: Conditional `Type`: String `Length`: 2-3 |
| zip_code | Payer’s ZIP code. | `Necessity`: Required `Type`: String `Length`: 10 |
| country | Payer’s country. Please see [Country codes](https://doc.payneteasy.com/integration/reference/country_codes.html.md) for a list of valid country codes. | `Necessity`: Required `Type`: String `Length`: 2 |
| phone | Payer’s full international phone number, including country code. | `Necessity`: Required `Type`: String `Length`: 15 |
| cell_phone | Payer’s full international cell phone number, including country code. | `Necessity`: Optional `Type`: String `Length`: 15 |
| email | Payer’s e-mail address. | `Necessity`: Required `Type`: String `Length`: 50 |
| purpose | Destination to where the payment goes. It is useful for the Connecting Party’s who let their payers to top up their accounts with bank card (Mobile phone accounts, game accounts etc.). Sample values are: +9999999999; mail@example.com etc. This value can be used by the fraud monitoring system. | `Necessity`: Optional `Type`: String `Length`: 128 |
| amount | Amount to be charged. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. | `Necessity`: Required `Type`: Numeric `Length`: 10 |
| currency | Currency the transaction is charged in (See: [Currency codes](https://doc.payneteasy.com/integration/reference/currency_codes.html.md)). Sample values are: USD for US Dollar EUR for European Euro. | `Necessity`: Required `Type`: String `Length`: 3 |
| ipaddress | Payer’s IP address, included for fraud screening purposes. | `Necessity`: Required `Type`: String `Length`: 20 |
| site_url | The URL of the E-commerce entity, where the payment is originated from. | `Necessity`: Optional `Type`: String `Length`: 128 |
| control | Checksum generated by [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md). Control string is represented as concatenation of the following parameters: 1. **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Parameter name | Description |
|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be async-form-response, validation-error, error etc.. If type equals validation-error or error, error-message and error-code parameters contain error details. |
| paynet-order-id | Order id assigned to the order by Payneteasy. |
| merchant-order-id | Connecting Party order id. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
| error-message | If status is declined or error this parameter contains the reason for decline or error details. |
| error-code | The error code in case of declined or error status. |
| redirect-url | The URL to the page where the Connecting Party should redirect the client’s browser. Connecting Party should send HTTP 302 redirect, see [General Payment-form Process Flow](https://doc.payneteasy.com/integration/api_use_cases/sale_form.html.md). |
#### Request Example
```http
POST /paynet/api/v2/sale-form/39519 HTTP/1.1
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 314
Content-Type: application/x-www-form-urlencoded
Connection: close
client_orderid=inv1409911
&order_desc=Test Order Description
&first_name=John
&last_name=Smith
&ssn=1267
&birthday=19820115
&address1=100 Main st
&city=Seattle
&state=WA
&zip_code=98102
&country=US
&phone=+12063582043
&cell_phone=+19023384543
&amount=156
&email=john.smith@gmail.com
¤cy=USD
&ipaddress=65.153.12.232
&site_url=https://doc.payneteasy.com
&purpose=user_account1
&redirect_url=http://connectingparty.com/result
&server_callback_url=https://httpstat.us/200
&merchant_data=VIP customer
&merchant_form_data=testparam%3Dtest1%26mynewparam%3Dtest2
&control=185aea68b751221b78fa9138e9d44a6aa4c2c446
```
#### Success Response Example
```http
HTTP/1.1 200 OK
Server: server
Date: Tue, 11 Oct 2022 14:25:25 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 280
type=async-form-response
&serial-number=00000000-0000-0000-0000-000002ddb0b9
&merchant-order-id=Test
&paynet-order-id=6863099
&redirect-url=https%3A%2F%2Fsandbox.payneteasy.eu%2Fpaynet%2Fform%2Finit%2FBB587546567A31587163597A68633370432F786752582F6154674965594A696F4D41306C50596E334F5453553D
```
#### Fail Response Example
```http
HTTP/1.1 200 OK
Server: server
Date: Tue, 11 Oct 2022 14:16:06 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 170
type=validation-error
&serial-number=00000000-0000-0000-0000-000002ddb0b7
&error-message=Project+with+currency+RUB+does+not+apply+request+with+currency+USD
&error-code=16
```
#### Open API Collection
Open this method in the OpenAPI Reference
View in OpenAPI
### /api/v2/sale
#### Introduction
Sale is initiated through HTTPS POST request by using [URLs](#api-v2-sale-request-url) and the [parameters](#api-v2-sale-request-parameters) specified below. Use [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md) for authentication. See [Statuses](https://doc.payneteasy.com/integration/reference/statuses.html.md).
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|------------------------------------------------------------------------|---------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v2/sale/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v2/sale/ENDPOINTID |
| https://sandbox.payneteasy.eu/paynet/api/v2/sale/group/ENDPOINTGROUPID | https://gate.payneteasy.eu/paynet/api/v2/sale/group/ENDPOINTGROUPID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded.
Acquirer can redefine the necessity of some fields so they become required instead of optional.
Leading and trailing whitespace in input parameters will be omitted.
> **Warning:** The following characters must be escaped in the parameter values: & + “.
| Parameter Name | Description | Value |
|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| client_orderid | Unique order identifier assigned by Connecting Party. | `Necessity`: Required `Type`: String `Length`: 128 |
| order_desc | Brief order description. | `Necessity`: Required `Type`: String `Length`: 64k |
| amount | Amount to be charged. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. | `Necessity`: Required `Type`: Numeric `Length`: 10 |
| currency | Currency the transaction is charged in (See: [Currency codes](https://doc.payneteasy.com/integration/reference/currency_codes.html.md)). Sample values are: USD for US Dollar EUR for European Euro. | `Necessity`: Required `Type`: String `Length`: 3 |
| address1 | Payer’s address line 1. (Please note that in some cases it is not possible to send address length more than 50 characters. Please contact your manager for more details.) | `Necessity`: Required `Type`: String `Length`: 256 |
| city | Payer’s city. | `Necessity`: Required `Type`: String `Length`: 50 |
| zip_code | Payer’s ZIP code. | `Necessity`: Required `Type`: String `Length`: 10 |
| country | Payer’s country. Please see [Country codes](https://doc.payneteasy.com/integration/reference/country_codes.html.md) for a list of valid country codes. | `Necessity`: Required `Type`: String `Length`: 2 |
| phone | Payer’s full international phone number, including country code. | `Necessity`: Required `Type`: String `Length`: 15 |
| email | Payer’s e-mail address. | `Necessity`: Required `Type`: String `Length`: 50 |
| ipaddress | Payer’s IP address, included for fraud screening purposes. | `Necessity`: Required `Type`: String `Length`: 45 |
| control | Checksum generated by [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md). Control string is represented as concatenation of the following parameters: 1. **Note:** Browser data for 3DS 2. X is gathered by Connecting Party system on 3DS authentication stage. For some processing channels, however, the browser data and/or Connecting Party URL for 3DS challenge results must be provided in initial transaction request. Please contact Support manager to clarify if these parameters should be included in request parameters.
The Connecting Party’s site needs to accurately populate the browser information for each transaction. This data can be obtained by Connecting Party’s servers. Ensure that the data is not altered or hard-coded, and that it is unique to each transaction.
| Parameter Name | Description | Value |
|----------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| customer_browser_accept_header | Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser. | `Necessity`: Required `Type`: String `Length`: 2048 |
| customer_browser_javascript_enabled | Boolean that represents the ability of the cardholder browser to execute Java Script. | `Necessity`: Required `Type`: Boolean `Length`: - |
| customer_browser_accept_language | Value representing the browser language as defined in IETF BCP47. | `Necessity`: Required `Type`: String `Length`: 8 |
| customer_browser_user_agent | Exact content of the HTTP user-agent header. | `Necessity`: Required `Type`: String `Length`: 2048 |
| customer_browser_info | If true, then the fields below must be present. | `Necessity`: Optional `Type`: Boolean `Length`: - |
| customer_browser_color_depth | Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Becomes required when browser_java Script_enabled = true. | `Necessity`: Optional `Type`: String `Length`: 2 |
| customer_browser_java_enabled | Boolean that represents the ability of the cardholder browser to execute Java. Becomes required when browser_java Script_enabled = true. | `Necessity`: Optional `Type`: Boolean `Length`: - |
| customer_browser_screen_height | Total height of the Cardholder’s screen in pixels. Becomes required when browser_java Script_enabled = true. | `Necessity`: Optional `Type`: Numeric `Length`: 6 |
| customer_browser_screen_width | Total width of the cardholder’s screen in pixels. Becomes required when browser_java Script_enabled = true. | `Necessity`: Optional `Type`: Numeric `Length`: 6 |
| customer_browser_time_zone | Time-zone offset in minutes between UTC and the Cardholder browser local time. Note that the offset is positive if the local time zone is behind UTC and negative if it is ahead. Becomes required when browser_java Script_enabled = true. | `Necessity`: Optional `Type`: String `Length`: 5 |
| tds_areq_notification_url, alias tds_cres_notification_url | Fully qualified URL of Connecting Party system that will receive the CRes message or Error Message. This CRes message must be sent to Connecting Party. See details here [Upload CRes Result](https://doc.payneteasy.com/integration/upload-cres-result.html.md). | `Necessity`: Optional `Type`: String `Length`: 256 |
##### For Payment Institutions
The PSP or Acquirer can fill the 3DS results for each transaction, if 3DS authentication is performed on their side.
| Parameter Name | Description | Value |
|------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------|
| tds_authentication_result_type | Type of result. Possible values are: - SIMPLE | `Type`: String `Length`: 6 |
| tds_authentication_result_authentication_type | Authentication Type. Indicates the type of authentication method the Issuer will use to challenge the Cardholder, whether in the ARes message or what was used by the ACS when in the RReq message. Possible values are: - 01 = Static - 02 = Dynamic - 03 = OOB - 04 = Decoupled - 05-79 = Reserved for EMVCo future use (values invalid until defined by EMVCo) - 80-99 = Reserved for DS use | `Type`: String `Length`: 2 |
| tds_authentication_result_authentication_value | Authentication Value. Payment System-specific value provided by the ACS or the DS using an algorithm defined by Payment System. Authentication Value may be used to provide proof of authentication. A 20-byte value that has been Base64 encoded, giving a 28-byte result | `Type`: String `Length`: 19-28 |
| tds_authentication_result_transaction_id | xid for 1.0.2 or ds TransID for 2.1.0/2.2.0 | `Type`: String `Length`: 19-36 |
| tds_authentication_result_transaction_status | Transaction Status. Indicates whether a transaction qualifies as an authenticated transaction or account verification. Possible values are: - Y = Authentication Verification Successful - N = Not Authenticated/Account Not Verified, Transaction denied - U = Authentication/Account Verification Could Not Be Performed, Technical or other problem, as indicated in ARes or RReq - A = Attempts Processing Performed, Not Authenticated/Verified, but a proof of attempted authentication/verification is provided - C = Challenge Required, Additional authentication is required using the CReq/CRes - D = Challenge Required, Decoupled Authentication confirmed - R = Authentication/ Account Verification Rejected, Issuer is rejecting | `Type`: String `Length`: 1 |
| tds_authentication_result_message_version | Message Version Number. Protocol version identifier This shall be the Protocol Version Number of the specification utilised by the system creating this message. The Message Version Number is set by the 3DS Server which originates the protocol with the AReq message. The Message Version Number does not change during a 3DS transaction. Possible values are: - 1.0.2 - 2.1.0 - 2.2.0 | `Type`: String `Length`: 5 |
#### Response Parameters
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Parameter Name | Description |
|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be async-response, validation-error, error etc.. If type equals validation-error or error, error-message and error-code parameters contain error details. |
| paynet-order-id | Order id assigned to the order by Payneteasy. |
| merchant-order-id | Connecting Party order id. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
| error-message | If status is declined or error this parameter contains the reason for decline or error details. |
| error-code | The error code in case of declined or error status. |
| end-point-id | Endpoint id used for the transaction. |
#### Request with Cardholder Data Example
```http
POST /paynet/api/v2/sale/39529 HTTP/1.1
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 314
Content-Type: application/x-www-form-urlencoded
Connection: close
credit_card_number=4538977399606732
&card_printed_name=John
&expire_month=01
&expire_year=2042
&cvv2=123
&client_orderid=34T43R77N
&order_desc=Test Order Description
&first_name=John
&last_name=Smith
&ssn=1267
&birthday=19820115
&address1=100%20Main%20st
&city=Seattle
&state=WA
&zip_code=98102
&country=US
&phone=+12063582043
&cell_phone=+19023384543
&amount=156
&email=john.smith@gmail.com
¤cy=RUB
&ipaddress=65.153.12.232
&site_url=https://doc.payneteasy.com
&purpose=user_account1
&redirect_url=http%3A%2F%2Fhttps://doc.payneteasy.com%2Fdoc%2Fdummy.htm
&server_callback_url=https%3A%2F%2Fhttpstat.us%2F200
&merchant_data=VIP customer
&dapi_imei=123
&control=c821e33bd22773c05c23725d0b1d2dbd9f191399
```
#### Request with Card Recurring Payment ID Example
```http
POST /paynet/api/v2/sale/39915 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 317
Content-Type: application/x-www-form-urlencoded
Connection: close
card_recurring_payment_id=1491954
&cvv2=123
&client_orderid=34T43R77N
&order_desc=Test Order Description
&amount=777
¤cy=USD
&ipaddress=65.153.12.232
&redirect_url=http://doc2.doc2.com/doc/dummy.htm
&server_callback_url=https://httpstat.us/200
&control=80761544c64373d1624240add048d36d42fe528a
```
#### Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Wed, 17 Nov 2021 11:03:17 GMT
Content-Type: text/html;charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Keep-Alive: timeout=60
Vary: Accept-Encoding
X-XSS-Protection: 1
Strict-Transport-Security: max-age=31536000
Content-Language: ru-RU
P3P: CP="NOI ADM DEV COM NAV OUR STP"
Content-Encoding: gzip
type=async-response
&serial-number=00000000-0000-0000-0000-000002d9b22a
&merchant-order-id=inv4097763
&paynet-order-id=6768788
&end-point-id=22903
```
#### Fail Response Example
```http
HTTP/1.1 200
Server: server
Date: Wed, 17 Nov 2021 13:14:40 GMT
Content-Type: text/html;charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Keep-Alive: timeout=60
Vary: Accept-Encoding
X-XSS-Protection: 1
Strict-Transport-Security: max-age=31536000
Content-Language: ru-RU
P3P: CP="NOI ADM DEV COM NAV OUR STP"
Content-Encoding: gzip
type=validation-error
&serial-number=00000000-0000-0000-0000-000002b36f64
&merchant-order-id=inv4097763
&error-message=End+point+with+id+22903+not+found
&error-code=3
```
#### Open API Collection
Open this method in the OpenAPI Reference
View in OpenAPI
### /api/v2/status
#### Introduction
To make an order status request one have to send an HTTPS POST request to the [URLs](#status-request-url) and the [parameters](#status-request-parameters) specified below. Use [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md) for authentication. See [Statuses](https://doc.payneteasy.com/integration/reference/statuses.html.md).
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|--------------------------------------------------------------------------|-----------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v2/status/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v2/status/ENDPOINTID |
| https://sandbox.payneteasy.eu/paynet/api/v2/status/group/ENDPOINTGROUPID | https://gate.payneteasy.eu/paynet/api/v2/status/group/ENDPOINTGROUPID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded.
| Parameter Name | Description | Necessity |
|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|
| login | Merchant login name. | Mandatory |
| client_orderid | Unique order identifier assigned by merchant. | Mandatory |
| orderid | Order id assigned to the order by Payneteasy. | Conditional |
| by-request-sn | Serial number assigned to the specific request by Payneteasy. If this field exist in status request, status response return for this specific request. Include this parameter to get the status request with the particular transaction stage (can be used in specific cases). To get the latest transaction status, don’t include this parameter in status request. | Optional |
| control | Checksum generated by [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md). Control string is represented as concatenation of the following parameters: 1. Request parameter: login. 2. Request parameter: client_orderid. 3. Request parameter: orderid. 4. merchant_control (Control key assigned to Connecting Party account in the Payneteasy gateway system). | Mandatory |
In most common cases, the best option is to include both client_orderid and orderid parameters to status request. Order status can be requested with only client_orderid if it’s unique to merchant and orderid is not received. If orderid is not received in response, but this response contains an error, see the received error message to get the information why transaction was not created in the system.
#### Response Parameters
The same API command for status request is used in multiple Use-Cases, therefore some of the mentioned response parameters might not be present for specific case. Below is the full list of possible parameters.
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
\* - these parameters are not defined by default. Please contact tech support to include these fields in callback.
| Status Response Parameter | Description |
|-------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be status-response. |
| status | See [Status List](https://doc.payneteasy.com/integration/reference/statuses.html.md) for details. |
| amount | Actual transaction amount. This value can be changed during the transaction flow. |
| currency | Currency the transaction is charged in (three-letter currency code). Example of valid parameter values are: USD for US Dollar EUR for European Euro. |
| paynet-order-id | Order id assigned to the order by gate.payneteasy.eu. |
| merchant-order-id | Connecting Party order id. |
| phone | Payer’s full international phone number, including country code. |
| html | HTML code of 3DS authorization form, encoded in application/x-www-form-urlencoded MIME format. Merchant must decode this parameter before showing the form to the Payer. gate.payneteasy.eu System returns the following response parameters when it gets 3DS authorization form from the Issuer Bank. It contains auth form HTML code which must be passed through without any changes to the client’s browser. This parameter exists and has value only when the redirection HTML is already available. For non-3DS this never happens. For 3DS HTML has value after some short time after the processing has been started. |
| redirect-to | For 3DS authorization the merchant can redirect the Payer to URL provided in this parameter instead of rendering the page provided in html parameter. The redirect-to parameter is returned only if the html parameter is returned. Merchant should use GET HTTP method to redirect. This parameter must be used to work with 3DS 2.0. |
| serial-number | Unique number assigned by gate.payneteasy.eu server to particular request from the Connecting Party. |
| last-four-digits | Last four digits of Payer bank card number. |
| dest-last-four-digits | Last four digits of customer credit card number. Relevant only for transfer transactions. |
| bin | Bank BIN of Payer bank card number. |
| card-type | Type of Payer bank card (VISA, MASTERCARD, etc). |
| gate-partial-reversal | Processing gate support partial reversal (enabled or disabled). |
| gate-partial-capture | Processing gate support partial capture (enabled or disabled). |
| transaction-type | Transaction type (sale, reversal, capture, preauth). |
| processor-rrn | Bank Receiver Registration Number. |
| processor-tx-id | Acquirer transaction identifier. |
| receipt-id | Electronic link to receipt https://gate.payneteasy.eu/paynet/view-receipt/ENDPOINTID/receipt-id/. |
| name | Payer’s name. |
| card-ref-id | Card reference ID used in subsequent recurrent payments. Relevant only if card-ref-id was created for initial transaction. |
| cardholder-name | Cardholder’s name. |
| card-exp-month | Bank card expiration month. |
| card-exp-year | Bank card expiration year. |
| card-hash-id | Unique card identifier to use for loyalty programs or fraud checks. |
| card-country-alpha-three-code | Three letter country code of source card issuer. See [Country and State Codes](https://doc.payneteasy.com/integration/reference/country_codes.html.md) for details. |
| destination-card-country-alpha-three-code | Three letter country code of destination card issuer. See [Country and State Codes](https://doc.payneteasy.com/integration/reference/country_codes.html.md) for details. |
| dest-bin | Bank BIN of customer credit card number. |
| dest-card-type | Type of customer credit card (VISA, MASTERCARD, etc). |
| dest-bank-name | Bank name by customer card BIN. |
| destination-hash-id | Unique card identifier to use for loyalty programs or fraud checks. Relevant only for transfer transactions. |
| destination-card-hash-id | Unique card identifier to use for loyalty programs or fraud checks. |
| first-name | Payer’s first name. |
| last-name | Payer’s last name. |
| email | Payer’s e-mail. |
| country \* | Payer’s country (two-letter country code). Please see [Country and State Codes](https://doc.payneteasy.com/integration/reference/country_codes.html.md) for a list of valid country codes. |
| state \* | Payer’s state . Please see [Country and State Codes](https://doc.payneteasy.com/integration/reference/country_codes.html.md) for a list of valid state codes. Mandatory for USA, Canada and Australia. |
| city \* | Payer’s city. |
| zip_code \* | Payer’s ZIP code. |
| address1 \* | Payer’s address line 1. |
| purpose | Destination to where the payment goes. It is useful for the merchants who let their payers to top up their accounts with bank card (Mobile phone accounts, game accounts etc.). Sample values are: +9999999999; mail@example.com etc. This value can be used by the fraud monitoring system. |
| bank-name | Bank name by Payer card BIN. |
| terminal-id | Acquirer terminal identifier to show in receipt. |
| paynet-processing-date | Acquirer transaction processing date. |
| approval-code | Bank approval code. |
| order-stage | The current stage of the transaction processing. See [Order Stage](https://doc.payneteasy.com/integration/reference/order_stage.html.md) for details. |
| total-reversal-amount | Total amount of processed reversals. Relevant only for reversal transactions. |
| reversal-amount | The amount of the last processed reversal. Relevant only for reversal transactions. |
| auth-response-code | Response code used in Iso8583 protocol. Only returned in specific cases. |
| acquirer-processing-date | Acquirer transaction processing date. |
| processor-auth-credit-code | Approval credit code. Only returned in specific cases. |
| processor-credit-rrn | Retrieval Reference Number for credit transaction. |
| processor-credit-arn | Acquirer card reference number for credit transaction. |
| processor-debit-arn | Acquirer card reference number for debit transaction. |
| loyalty-balance | The current bonuses balance of the loyalty program for current operation. if available. |
| loyalty-message | The message from the loyalty program. if available. |
| loyalty-bonus | The bonus value of the loyalty program for current operation if available. |
| loyalty-program | The name of the loyalty program for current operation if available. |
| descriptor | Bank identifier of the payment recipient. |
| original-gate-descriptor | Descriptor, which is set on gate level in the system. |
| error-message | If status in declined, error, filtered this parameter contains the reason for decline. |
| error-code | The error code is case status in declined, error, filtered. |
| by-request-sn | Serial number assigned to the specific request by gate.payneteasy.eu. If this field exist in status request, status response return for this specific request. |
| verified-3d-status | See [3D Secure Status List](https://doc.payneteasy.com/integration/reference/statuses.html.md) for details. |
| verified-rsc-status | Returned if Random Sum Check was performed. See [Alternative cardholder authentication](https://doc.payneteasy.com/integration/reference/3ds_overview.html.md) |
| eci | Electronic Commerce Indicator (Visa). |
| ips-src-payment-product-code | Code for card set by multinational financial service (Visa/Mastercard). |
| ips-src-payment-product-name | Decrypted code for card set by multinational financial service (Visa/Mastercard). |
| ips-src-payment-type-code | Type of card code set by multinational financial service (Visa/Mastercard). |
| ips-src-payment-type-name | Decrypted code for type of card set by multinational financial service (Visa/Mastercard). |
| merchantdata | If provided in initial request, merchant_data parameter and its value will be included in status response. |
| initial-amount | Amount, set in initiating transaction, without any fees or commissions. This value can’t change during the transaction flow. |
| seller-commission | Total commission for processed transaction. This is optional parameter. Please contact your manager in Payneteasy, if you would like to receive it. |
| acquirer-commission | Acquirer commission for processed transaction. This is optional parameter. Please contact your manager in Payneteasy, if you would like to receive it. |
| motivational-message | This is an optional message which contains extended information about the reason for the declined transaction. |
| transaction-date | Date of final status assignment for transaction. |
| orig-amount | Contains the original request amount if it was converted on auxiliary endpoint in Parallel form integration. Relevant only for Payment Cashier transactions. |
| orig-currency | Contains the original request currency if it was converted on auxiliary endpoint in Parallel form integration. Relevant only for Payment Cashier transactions. |
#### Pa Req Form Status Response Parameters
| Name | Description |
|------------------------|-----------------------------------------------------------------|
| tds-pareq-form-pareq | ACS 3DS Pa Req data, which received by the Connecting Party. |
| tds-pareq-form-acs-url | ACS URL to redirect the Payer to 3DS 1.0.2 Authentication Flow. |
#### CReq Form Status Response Parameters
| Name | Description |
|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| tds-creq-form-creq | A CReq message initiates Cardholder interaction in a Challenge Flow and is used to carry authentication data from the Cardholder. It is formed by the 3DS Server and is posted through the Cardholder’s browser by the merchant to the ACS URL. |
| tds-creq-form-acs-url | ACS URL to redirect the Payer for Challenge Flow. |
#### Method Url Frame Status Response Parameters
| Name | Description |
|------------------------------------------|--------------------------------------------------------------------------------------------------------|
| tds-method-url-frame-3ds-server-trans-id | Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction. |
| tds-method-url-frame-3ds-method-url | 3DS Method URL used in iframe form which is provided to Payer browser by the merchant. |
Rules to form the HTML form.
threeDSMethod Data (threeDSMethod NotificationURL + threeDSServer TransID).
#### Request Example
```http
POST /paynet/api/v2/status/37211 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.77.0
Accept: */*
Content-Length: 99
Content-Type: application/x-www-form-urlencoded
Connection: close
login=TestYujik
&client_orderid=123
&orderid=6863082
&control=647f0581bbceb804a73e98d9ea7e78640a75bf1c
```
#### Success Response Example
```http
HTTP/1.1 200 OK
Server: server
Date: Mon, 12 Sep 2022 09:02:42 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
X-Cached: EXPIRED
Content-Length: 1275
type=status-response
&serial-number=00000000-0000-0000-0000-000002ddb056
&merchant-order-id=123
&processor-tx-id=PNTEST-6863082
&paynet-order-id=6863082
&status=approved
&amount=555.00
¤cy=USD
&descriptor=XXXX
&original-gate-descriptor=XXXX
&gate-partial-reversal=enabled
&gate-partial-capture=enabled
&transaction-type=sale
&receipt-id=081c0c0b-0dd1-3083-b251-e624ac8e57b4
&name=CARD+HOLDER
&cardholder-name=CARD+HOLDER
&card-exp-month=12
&card-exp-year=2099
&email=john.smith%40gmail.com
&last-name=Smith
&first-name=John
&processor-rrn=0225083062885
&approval-code=979249
&order-stage=sale_approved
&merchantdata=VIP+customer
&last-four-digits=2063
&bin=410002
&card-type=VISA
&phone=12063582043
&bank-name=BANCO+ITAUCARD+S.A.
&auth-response-code=00
&terminal-id=12345678
&paynet-processing-date=2022-09-07+13%3A22%3A39+MSK
&acquirer-processing-date=2022-09-07+13%3A22%3A39+MSK
&processor-auth-credit-code=206551
&card-hash-id=2639503
&card-country-alpha-three-code=BRA
&verified-3d-status=NOT_AUTHENTICATED
&processor-credit-rrn=0225060914211
&processor-credit-arn=809124106
&processor-debit-arn=601904020
&purpose=user_account1
&ips-src-payment-product-code=F
&ips-src-payment-product-name=Visa+Classic
&ips-src-payment-type-code=Credit
&ips-src-payment-type-name=VISA+Credit
&initial-amount=555.00
```
#### Fail Response Example
```http
HTTP/1.1 200 OK
Server: server
Date: Mon, 12 Sep 2022 09:08:02 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
X-Cached: MISS
Content-Length: 137
type=validation-error
&serial-number=00000000-0000-0000-0000-000002ddb057
&error-message=End+point+with+id+372118+not+found
&error-code=3
```
#### Open API Collection
Open this method in the OpenAPI Reference
View in OpenAPI
### /api/v2/void
#### Introduction
Void can only be processed for Sale and Capture transactions in the final successful status (See [Statuses](https://doc.payneteasy.com/integration/reference/statuses.html.md)). To make a void request send an HTTPS POST request to the [URLs](#api-v2-void-request-url) and the [parameters](#api-v2-void-request-parameters-url). Use [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md) for authentication.
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|------------------------------------------------------------------------|--------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v2/void/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v2/void/ENDPOINTID |
| https://sandbox.payneteasy.eu/paynet/api/v2/void/group/ENDPOINTGROUPID | https://gate.payneteasy.eu/paynet/api/v2/void/void/ENDPOINTGROUPID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded.
> **Warning:** The following characters must be escaped in the parameter values: & + “.
| Parameter Name | Description | Value |
|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| login | Connecting Party login name. | `Necessity`: Mandatory `Type`: String `Length`: 20 |
| orderid | Unique order identifier assigned by Payneteasy system. | `Necessity`: Mandatory `Type`: String `Length`: 20 |
| client_orderid | Unique Connecting Party identifier. | `Necessity`: Mandatory `Type`: Numeric `Length`: 10 |
| amount | This optional parameter specifies amount to be reversed. | `Necessity`: Mandatory `Type`: String `Length`: 10 |
| currency | Currency the transaction is charged in (See: [Currency codes](https://doc.payneteasy.com/integration/reference/currency_codes.html.md)). Sample values are: USD for US Dollar EUR for European Euro. | `Necessity`: Conditional `Type`: String `Length`: 3 |
| control | Checksum generated by [SHA-1](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/sha.html.md). Control string is represented as concatenation of the following parameters: 1. Request parameter: login 2. Request parameter: client_orderid 3. Request parameter: orderid 4. merchant_control (Control key assigned to Connecting Party account in the Payneteasy gateway system). | `Necessity`: Conditional `Type`: String `Length`: 128 |
| comment | A brief description of reason. | `Necessity`: Mandatory `Type`: String `Length`: 50 |
#### Response Parameters
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Parameter Name | Description |
|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be async-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details |
| paynet-order-id | Order id assigned to the order by Payneteasy. |
| merchant-order-id | Connecting Party order id. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
| end-point-id | Entry point used for processing this transaction. |
| error-message | If status is error this parameter contains the reason for decline or error details. |
| error-code | The error code is case of error status. |
#### Request Example
```http
POST /paynet/api/v2/void/39914 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 123
Content-Type: application/x-www-form-urlencoded
Connection: close
login=Test
&client_orderid=55
&orderid=6862995
&comment=Service not provided
&control=246e0a2074f9e4b84cff59b2567ed48ec3aab87d
```
#### Success Response Example
```http
HTTP/1.1 200 OK
Server: server
Date: Tue, 16 Aug 2022 06:57:40 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 138
type=async-response
&serial-number=00000000-0000-0000-0000-000002ddae76
&merchant-order-id=55
&paynet-order-id=6862995
&end-point-id=39914
```
#### Fail Response Example
```http
HTTP/1.1 200 OK
Server: server
Date: Tue, 16 Aug 2022 07:21:37 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 148
type=validation-error
&serial-number=00000000-0000-0000-0000-000002ddae78
&merchant-order-id=Test
&error-message=INVALID_CONTROL_CODE
&error-code=2
```
#### Open API Collection
Open this method in the OpenAPI Reference
View in OpenAPI
### /api/v4/create-card-ref
#### Introduction
Card reference ID and Recurring Payment ID creation is initiated through HTTPS POST request by using [URLs](#api-v4-card-ref-id-request-url) and the [parameters](#v4-card-ref-id-request-parameters) specified below. Use [OAuth RSA-SHA256](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md) for authentication.
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|-----------------------------------------------------------------------------------|--------------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v4/create-card-ref/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v4/create-card-ref/ENDPOINTID |
| https://sandbox.payneteasy.eu/paynet/api/v4/create-card-ref/group/ENDPOINTGROUPID | https://gate.payneteasy.eu/paynet/api/v4/create-card-ref/group/ENDPOINTGROUPID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded and [Authorization headers](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md).
| Sale Request Parameters | Description |
|---------------------------|---------------------------------------------------------------------|
| login | Connecting Party’s login name. |
| client_orderid | Connecting Party’s order identifier of the transaction. |
| orderid | Transaction order identifier assigned by Payment Gateway. |
Connecting Party has to supply orderid and client_orderid associated with the first payment transaction. It emphasizes that the first payment is a mandatory step to process recurring payments. To authorize the credit card the information about it must be sufficient and an initial payment must be in [final status](https://doc.payneteasy.com/integration/reference/statuses.html.md).
#### Response Parameters
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Registration Response Parameter | Description |
|-----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be create-card-ref-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
| card-ref-id | Card reference ID used in subsequent recurring payments. |
| unq-card-ref-id | Unique card reference ID to each PAN. It can be used by Connecting Party for loyalty programs or fraud control. |
| recurring-payment-id | Payer’s tokenized cardholder’s data ID, referred as Recurring Payment ID (RPI). |
| dst-card-ref-id | Receiver’s card reference ID used in subsequent recurring payments. Can be used only in transfer APIs. |
| dst-unq-card-ref-id | Receiver’s unique card reference ID to each PAN. It can be used by Connecting Party for loyalty programs or fraud control. Can be used only in transfer APIs. |
| dst-recurring-payment-id | Receiver’s tokenized cardholder’s data ID, referred as Recurring Payment ID (RPI). Can be used only in transfer APIs. |
| error-message | If status is declined or error this parameter contains the reason for decline. |
| error-code | The error code is case of declined or error status. |
| status | See [Status List](https://doc.payneteasy.com/integration/reference/statuses.html.md) for details. |
#### Request Example
```http
POST /paynet/api/v4/create-card-ref/39915 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth oauth_consumer_key="TestMerchant", oauth_nonce="KT6cZmuVGqg0V6Jm2RE3q4o79KXC1v2q", oauth_signature="KucF0eYk3WZCV7oKwOi1z6PR%2BkHxiZwPucD6Sx%2BX2mV%2BbaidPy9K9USh8ciMKM60NNl1LYYjywdaErB1uTIdFFbQ8ZKs8M1smaMPOaHDaApceTOlDh6E7u3BzBTKYhBc%2BWnksZz9Wyz8%2B39lHCIODo0KZmNmXCTjjZmlx%2FrFNkK%2FhwJV9Kwq1nPbA5QZTkF686O0O0lHFy3Prx649AIRgsrqDLb5%2FgHL9M8fSScVUPnGdLGJ2hSgKJFpIOFibT0nC89Xg8odn1hR9WIa1650glaqZntSkocBzXAkOKa7kIbSOZW1sFCiBjksy6o1sny9hmc%2F9cC9t86RoEY1QhVYuvOLztQm1dLhpRy%2FPOL9LCmIzO3B%2FUB2wJUXPkEyFsSLZVeqQl%2B0IukljV6Cr1ZfuyUktbvvXJsnod5AK%2FsV2GaxEf%2BttqqWv%2FFNjPLoUZYrPB6rKsIpw%2FOftinIwIxYzLY3FMmbKQd6zxnMJLJm7M2s6cQFGiAnfgvZFAMZhugBuuigy4T9Ckq1t5N9vQkl2htDv0TTnswx50wpF%2F7OKiXTVFNqOE%2FCj%2F07ZwZbxbD%2FMxKhOhfNMME1jGxzgI0wEj1166eKpxnCOk%2BTlYTJvNW5%2BbKuGnU43Q2Nmga0aQ007NKRfIV%2FWk6e%2BUuGO48wGdi0CiKxS9hpnpvjyPLc%2BsA%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1673335450", oauth_version="1.0"
Content-Length: 40
Content-Type: application/x-www-form-urlencoded
Connection: close
client_orderid=34T43R77N
&orderid=6868305
```
#### Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Tue, 10 Jan 2023 07:24:36 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 174
type=create-card-ref-response
&serial-number=00000000-0000-0000-0000-000002de3113
&card-ref-id=1461608
&recurring-payment-id=1491863
&dst-card-ref-id=1461608
&status=approved
```
#### Fail Response Example
```http
HTTP/1.1 403
Server: server
Date: Tue, 10 Jan 2023 07:34:08 GMT
Content-Type: text/html
Content-Length: 735
Connection: close
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
403
Access is denied
```
#### Open API Collection
Open this method in the OpenAPI Reference
View in OpenAPI
### /api/v4/create-recurring-payment
#### Introduction
/api/v4/create-recurring-payment is a synchronous API command. If request is accepted with no errors, the Payment Gateway creates a recurring payment profile and assigns a new recurring-payment-id to it. The recurring transactions will be processed according to the created recurring payment profile using the payment data saved in this profile.
Create recurring payment is initiated through HTTPS POST request by using [URLs](#api-v4-create-recurring-payment-request-url) and the [parameters](#api-v4-create-recurring-payment-request-parameters) specified below. Use [OAuth RSA-SHA256](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md) for authentication.
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|---------------------------------------------------------------------------------|------------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v4/create-recurring-payment/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v4/create-recurring-payment/ENDPOINTID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded and [Authorization headers](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md).
> **Note:** If the recurrent has switched to Stopped, you can update its schedule using the start-date and finish-date parameters. However, it can only be resumed via the UI by clicking on Resume.
Type native on UI means that The recurring payment setup and the actual charges are in the same acquirer.
To create recurring payment profile with automatic recurring schedule, send interval and period parameters. To create recurring payment profile without automatic recurring schedule, do not send interval and period parameters. To stop the automatic recurring schedule, use [/api/v4/update-recurring-payment](https://doc.payneteasy.com/integration/api_v4_update-recurring-payment.html.md). Available only for SRC.
| Parameter Name | Description | Value |
|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------|
| rp_card_type | SRC - Sender’s source card. DST - Receiver’s destination card. | `Necessity`: Required `Type`: Enum `Length`: 3 |
| client-orderid | Connecting Party order ID. Supported for SRC and DST type. | `Necessity`: Required `Type`: String `Length`: 128 |
| credit-card-number | Payer\`s credit card number. Supported for SRC and DST type. | `Necessity`: Required `Type`: Numeric `Length`: 19 |
| cvv2 | Payer’s CVV2 code. CVV2 (Card Verification Value) is a three- or four-digit number printed on the back of the card in the signature area. | `Necessity`: Optional `Type`: Numeric `Length`: 3-4 |
| card-printed-name | Payer\`s card printed name. Required for SRC, optional for DST. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| expire-year | Payer\`s card expire year. Required for SRC, optional for DST. | `Necessity`: Conditional `Type`: Numeric `Length`: 4 |
| expire-month | Payer\`s card expire month. Required for SRC, optional for DST. | `Necessity`: Conditional `Type`: Numeric `Length`: 2 |
| amount | Amount of currency must be the same as currency on the project assigned. Upon reaching finish date, Recurring payment will go into stop status. Supported for SRC and DST type. Required if amount-from and amount-to or amount-sequence are not used. | `Necessity`: Conditional `Type`: Numeric `Length`: 10 |
| currency | Currency type. Supported for SRC and DST type. | `Necessity`: Required `Type`: String `Length`: 3 |
| country | Payer\`s country. Not supported for DST. | `Necessity`: Required `Type`: String `Length`: 2 |
| city | Payer\`s city. Not supported for DST. | `Necessity`: Required `Type`: String `Length`: 128 |
| zip-code | Payer\`s zip-code. Not supported for DST. | `Necessity`: Required `Type`: String `Length`: 10 |
| address1 | Payer\`s address. Not supported for DST. | `Necessity`: Required `Type`: String `Length`: 256 |
| first-name | Payer\`s first-name. Not supported for DST. | `Necessity`: Required `Type`: String `Length`: 128 |
| last-name | Payer\`s last-name. Not supported for DST. | `Necessity`: Required `Type`: String `Length`: 128 |
| email | Payer\`s email. Not supported for DST. | `Necessity`: Required `Type`: String `Length`: 128 |
| amount-from | If the combination of amount-from and amount-to is chosen, every charge will be of random amount between these two numbers. Supported for SRC and DST type. Required if amount or amount-sequence are not used. | `Necessity`: Conditional `Type`: Numeric `Length`: 10 |
| amount-to | If the combination of amount-from and amount-to is chosen, every charge will be of random amount between these two numbers. Supported for SRC and DST type. Required if amount or amount-sequence are not used. | `Necessity`: Conditional `Type`: Numeric `Length`: 10 |
| amount-sequence | If amount sequence is chosen, client will be charged amounts from this list. Example of setting up amount sequence: 10.5, 24.6, 32.0. If repeats number is higher than amount sequence number of elements, every new charge will be with last amount in amount sequence. In order for charges to begin from the first amount in the chain, current repeats number must be set as 0. Supported for SRC and DST type. Required if amount-from and amount-to or amount are not used. | `Necessity`: Conditional `Type`: Numeric `Length`: 10 |
| period | Possible values are: day, week and month. In case if daily is chosen, client will be charged every day. If week - every 7 days. If monthly is chosen, client will be charged on the same date of the month, from the starting date, no matter how many days there are in a month. Interval and period can only be specified or omitted together. Not supported for DST. | `Necessity`: Conditional `Type`: String `Length`: 32 |
| interval | Interval is a multiplier applied to the period. For example, if interval of 2 and period ‘Daily’ is selected, client will be charged once every 2 days. Interval and period can only be specified or omitted together. Not supported for DST. | `Necessity`: Conditional `Type`: Int `Length`: - |
| order_desc | Description of Recurring payment. Supported for SRC and DST type. | `Necessity`: Optional `Type`: String `Length`: 65K |
| customer-ip | Payer\`s IP address. Supported for SRC and DST type. | `Necessity`: Optional `Type`: String `Length`: 45 |
| ssn | Social security number field. Not supported for DST. | `Necessity`: Optional `Type`: String `Length`: 32 |
| birthday | Payer\`s birthday date. Not supported for DST. | `Necessity`: Optional `Type`: 8/Numeric, DD.MM.YYYY `Length`: 8 |
| phone | Payer\`s phone number. Not supported for DST. | `Necessity`: Optional `Type`: String `Length`: 128 |
| state | Payer’s state. Please see [Mandatory State codes](https://doc.payneteasy.com/integration/reference/country_codes.html.md) for a list of valid state codes. Required for USA, Canada and Australia. Not supported for DST. | `Necessity`: Optional `Type`: String `Length`: 2-3 |
| start-date | Date, when first charge is scheduled. If start date is set as a current date and type is set as auto, first charge will be made today. Supported for SRC and DST type. | `Necessity`: Optional `Type`: 8/Numeric, DD.MM.YYYY `Length`: 8 |
| finish-date | Date, when the Payer will be charged last time. Supported for SRC and DST type. | `Necessity`: Optional `Type`: 8/Numeric, DD.MM.YYYY `Length`: 8 |
| max-repeats-number | Index of recurring transaction, first charge will hold the index of 0. Current repeats number increases even if a charge was unsuccessful. When current repeats number reaches max repeats number, Recurring payment goes into stop status and client is charged no more. If a charge was made automatically, no additional charges will be made (unless done manually), even if a recurring payment is stopped and rescheduled again. Supported for SRC and DST type. | `Necessity`: Optional `Type`: Int `Length`: - |
| purpose | Purpose of transaction. Not supported for DST. | `Necessity`: Optional `Type`: String `Length`: 128 |
| notify_url | Notify url field. server_callback_url parameter can also be used. For more information please see [Connecting Party Callbacks](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). Supported for SRC and DST type. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| server_callback_url | Connecting Party URL which will receive callback request once the transaction reaches final status. Connecting Party may use Server Callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. See callback details in [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). Send either notify_url or server_callback_url, not both. | `Necessity`: Optional `Type`: String `Length`: 128 |
#### Response Parameters
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
> **Warning:** /api/v4/create-recurring-payment is a synchronous API command. The response will be returned after the recurring payment profile will be created on Payment Gateway side.
| Response Parameters | Description |
|-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be create-recurring-payment-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details. |
| recurring-payment-id | Recurring ID assigned to the order by Payneteasy. |
| status | If request is accepted, this parameter has approved value. This is not a transaction status. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
| error-message | If status is declined or error this parameter contains the reason for decline or error details. |
| error-code | The error code in case of declined or error status. |
#### Request Example
```http
POST /paynet/api/v4/create-recurring-payment/ HTTP/1.1
User-Agent: curl/8.4.0
Accept: */*
Authorization: OAuth oauth_consumer_key="ErwinTestMerchant", oauth_nonce="qdyD66xc8sDEQwo3r12VjJfJhAOXuj6O", oauth_signature="eZve%2FSvPCTBXtQM%2BEwTEROtsQE27gZJr36EThL8ECCrnWH9Xw8JxcysNEPTG5HfcYwR2IOjDk3uiSNFa1oT2bQT9XONQTl1JVTOhIiMrMJT7GT1rGuLSsEvghaBoRLrcth6SC0c%2F%2FINyOxmIc%2B79E3T8hkpH6J6VI%2BSRG162%2BlHBPc1u1SGGnhkkRYU621AUGu2FDrc4neob4QJSm%2BaF3a0AgWDGiLbeQ0Ivn3YJ441EKd99kBWdaCuUp0eSfcmh3U2Js66edCjWXDEW7uuywP%2BU%2FBEeq06XxoVNGE2NF2LArXgoNqfzz2Tpisq35%2FE7Yg%2F9hphww75HMoJCECe0yVIHmKXd8HBDNMyT7gg3w5bnKbo%2FURX0m%2Fpe7bxkJ1mLNsKouHVkvjLZKpWVVUyCl%2BJ3x0BoEN5QK7xh0fNbV4Ue9TUOz59q0v%2B7lz5E1B4TvxQ9pa%2FmNCl4P2JgTosLvXNcdGn9Dq0TC0gb62O2W81MoZAljJQew%2FcKAUFTXBMZK6eIXzA81BPQVejv8nIVsvHKNo2Ko0s3hJPKGaeVAN0gyUAPw0%2BsJI3bnN2CPSW92xysGRWJYBtsHhqDhmgtoDNvw7LFB6BzRk5GPa9iQju34l47GsCUUIs3%2ByipIl7Q3HnM%2Bet9L8JSl7K02MwR6zlLxtd9UXHDq3pnmKzly6I%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1721312072", oauth_version="1.0"
Content-Length: 595
Content-Type: application/x-www-form-urlencoded
Connection: keep-alive
address1=1234%20Peace%20street
&amount=55
&birthday=1980-01-02
&card-printed-name=JOHN%20SMITH
&city=Chicago
&client-orderid=1575634981130
&country=US
&credit-card-number=4464920026265488
¤cy=USD
&customer-ip=1.2.3.4
&cvv2=123
&email=john.smith%40example.com
&expire-month=12
&expire-year=2040
&finish-date=2040-01-01
&first-name=John
&interval=1
&last-name=Smith
&max-repeats-number=1000
¬ify-url=http%3A%2F%2Fexample.com%2Fnotify-me
&order_desc=testing%20purposes
&period=week
&phone=12345678
&purpose=No%20purpose%20at%20all
&rp_card_type=SRC
&ssn=1234
&start-date=2030-01-01
&state=IL
&zip-code=123456
&server_callback_url=https://httpstat.us/200
```
#### Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Thu, 18 Jul 2024 14:16:20 GMT
Content-Type: text/html;charset=utf-8
Connection: keep-alive
Keep-Alive: timeout=60
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 137
type=create-recurring-payment-response
&serial-number=00000000-0000-0000-0000-000002f36d81
&recurring-payment-id=1492124
&status=approved
```
#### Fail Response Example
```http
HTTP/1.1 500
Server: server
Date: Thu, 18 Jul 2024 14:24:28 GMT
Content-Length: 61
Connection: keep-alive
Keep-Alive: timeout=60
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Internal server error [8485772c-21d6-42aa-b2eb-3b5ae4e07d19]
```
#### Open API Collection
Open this method in the OpenAPI Reference
View in OpenAPI
### /api/v4/create-recurring-payments
#### Introduction
If request is accepted with no errors, the Payment Gateway creates separate recurring payment profiles for each entry provided in the request and assigns new recurring-payment-id to each of them. The recurring transactions will be processed according to the created recurring payment profiles using the payment data saved in each profile.
Create recurring payments Multiple is initiated through HTTPS POST request by using [URLs](#api-v4-create-recurring-payments-request-url) and the [parameters](#api-v4-create-recurring-payments-request-parameters) specified below. Use [OAuth RSA-SHA256](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md) for authentication.
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|----------------------------------------------------------------------------------|-------------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v4/create-recurring-payments/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v4/create-recurring-payments/ENDPOINTID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded and [Authorization headers](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md).
Below is a description of each parameter that can be included in the CSV and added to payload parameter which will be used in the request.
The recurring payment profile details can be viewed only via UI.
> **Note:** If the recurrent has switched to Stopped, you can update its schedule using the start-date and finish-date parameters. However, it can only be resumed via the UI by clicking on Resume.
Type native on UI means that The recurring payment setup and the actual charges are in the same acquirer.
To create recurring payment profile with automatic recurring schedule, send interval and period parameters. To create recurring payment profile without automatic recurring schedule, do not send interval and period parameters. To stop the automatic recurring schedule, use [/api/v4/update-recurring-payments](https://doc.payneteasy.com/integration/api_v4_update-recurring-payments.html.md). Available only for SRC.
| CSV Parameter Name | Description | Value |
|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------|
| rp_card_type | SRC - Sender’s source card. DST - Receiver’s destination card. | `Necessity`: Required `Type`: Enum `Length`: 3 |
| client-orderid | Connecting Party order ID. Supported for SRC and DST type. | `Necessity`: Required `Type`: String `Length`: 128 |
| credit-card-number | Payer\`s credit card number. Supported for SRC and DST type. | `Necessity`: Required `Type`: Numeric `Length`: 19 |
| cvv2 | Payer’s CVV2 code. CVV2 (Card Verification Value) is a three- or four-digit number printed on the back of the card in the signature area. | `Necessity`: Optional `Type`: Numeric `Length`: 3-4 |
| card-printed-name | Payer\`s card printed name. Required for SRC, optional for DST. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| expire-year | Payer\`s card expire year. Required for SRC, optional for DST. | `Necessity`: Conditional `Type`: Numeric `Length`: 4 |
| expire-month | Payer\`s card expire month. Required for SRC, optional for DST. | `Necessity`: Conditional `Type`: Numeric `Length`: 2 |
| amount | Amount of currency must be the same as currency on the project assigned. Upon reaching finish date, Recurring payment will go into stop status. Supported for SRC and DST type. Required if amount-from and amount-to or amount-sequence are not used. | `Necessity`: Conditional `Type`: Numeric `Length`: 10 |
| currency | Currency type. Supported for SRC and DST type. | `Necessity`: Required `Type`: String `Length`: 3 |
| country | Payer\`s country. Not supported for DST. | `Necessity`: Required `Type`: String `Length`: 2 |
| city | Payer\`s city. Not supported for DST. | `Necessity`: Required `Type`: String `Length`: 128 |
| zip-code | Payer\`s zip-code. Not supported for DST. | `Necessity`: Required `Type`: String `Length`: 10 |
| address1 | Payer\`s address. Not supported for DST. | `Necessity`: Required `Type`: String `Length`: 256 |
| first-name | Payer\`s first-name. Not supported for DST. | `Necessity`: Required `Type`: String `Length`: 128 |
| last-name | Payer\`s last-name. Not supported for DST. | `Necessity`: Required `Type`: String `Length`: 128 |
| email | Payer\`s email. Not supported for DST. | `Necessity`: Required `Type`: String `Length`: 128 |
| amount-from | If the combination of amount-from and amount-to is chosen, every charge will be of random amount between these two numbers. Supported for SRC and DST type. Required if amount or amount-sequence are not used. | `Necessity`: Conditional `Type`: Numeric `Length`: 10 |
| amount-to | If the combination of amount-from and amount-to is chosen, every charge will be of random amount between these two numbers. Supported for SRC and DST type. Required if amount or amount-sequence are not used. | `Necessity`: Conditional `Type`: Numeric `Length`: 10 |
| amount-sequence | If amount sequence is chosen, client will be charged amounts from this list. Example of setting up amount sequence: 10.5, 24.6, 32.0. If repeats number is higher than amount sequence number of elements, every new charge will be with last amount in amount sequence. In order for charges to begin from the first amount in the chain, current repeats number must be set as 0. Supported for SRC and DST type. Required if amount-from and amount-to or amount are not used. | `Necessity`: Conditional `Type`: Numeric `Length`: 10 |
| period | Possible values are: day, week and month. In case if daily is chosen, client will be charged every day. If week - every 7 days. If monthly is chosen, client will be charged on the same date of the month, from the starting date, no matter how many days there are in a month. Interval and period can only be specified or omitted together. Not supported for DST. | `Necessity`: Conditional `Type`: String `Length`: 32 |
| interval | Interval is a multiplier applied to the period. For example, if interval of 2 and period ‘Daily’ is selected, client will be charged once every 2 days. Interval and period can only be specified or omitted together. Not supported for DST. | `Necessity`: Conditional `Type`: Int `Length`: - |
| order_desc | Description of Recurring payment. Supported for SRC and DST type. | `Necessity`: Optional `Type`: String `Length`: 65K |
| customer-ip | Payer\`s IP address. Supported for SRC and DST type. | `Necessity`: Optional `Type`: String `Length`: 45 |
| ssn | Social security number field. Not supported for DST. | `Necessity`: Optional `Type`: String `Length`: 32 |
| birthday | Payer\`s birthday date. Not supported for DST. | `Necessity`: Optional `Type`: 8/Numeric, DD.MM.YYYY `Length`: 8 |
| phone | Payer\`s phone number. Not supported for DST. | `Necessity`: Optional `Type`: String `Length`: 128 |
| state | Payer’s state. Please see [Mandatory State codes](https://doc.payneteasy.com/integration/reference/country_codes.html.md) for a list of valid state codes. Required for USA, Canada and Australia. Not supported for DST. | `Necessity`: Optional `Type`: String `Length`: 2-3 |
| start-date | Date, when first charge is scheduled. If start date is set as a current date and type is set as auto, first charge will be made today. Supported for SRC and DST type. | `Necessity`: Optional `Type`: 8/Numeric, DD.MM.YYYY `Length`: 8 |
| finish-date | Date, when the Payer will be charged last time. Supported for SRC and DST type. | `Necessity`: Optional `Type`: 8/Numeric, DD.MM.YYYY `Length`: 8 |
| max-repeats-number | Index of recurring transaction, first charge will hold the index of 0. Current repeats number increases even if a charge was unsuccessful. When current repeats number reaches max repeats number, Recurring payment goes into stop status and client is charged no more. If a charge was made automatically, no additional charges will be made (unless done manually), even if a recurring payment is stopped and rescheduled again. Supported for SRC and DST type. | `Necessity`: Optional `Type`: Int `Length`: - |
| purpose | Purpose of transaction. Not supported for DST. | `Necessity`: Optional `Type`: String `Length`: 128 |
| notify_url | Notify url field. server_callback_url parameter can also be used. For more information please see [Connecting Party Callbacks](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). Supported for SRC and DST type. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| server_callback_url | Connecting Party URL which will receive callback request once the transaction reaches final status. Connecting Party may use Server Callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. See callback details in [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). Send either notify_url or server_callback_url, not both. | `Necessity`: Optional `Type`: String `Length`: 128 |
#### Response Parameters
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Response Parameters | Description |
|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be create-recurring-payment-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details. Multiple error codes may be received: 200, 403, and 500. For the 500 error code, an additional error ID will be returned. |
| recurring-payment-id | Recurring ID assigned to the order by Payneteasy. |
| status | See [Status List](https://doc.payneteasy.com/integration/reference/statuses.html.md) for details. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
#### Request Example
**Step 1.** Create a CSV with the provided structure:
```http
"client-orderid";"rp_card_type";"payment-description";"first-name";"last-name";"address1";"city";"zip-code";
"country";"state";"phone";"email";"customer-ip";"period";"interval";"start-date";"finish-date";"max-repeats-number";"amount";
"amount-from";"amount-to";"amount-sequence";"currency";"card-printed-name";"credit-card-number";"expire-month";"expire-year"
```
**Step 2.** Encode CSV to base64 with the following command:
```bash
base64 create-recurring-payments-example.csv
```
**Step 3**. Assign the base64 encoded value to payload parameter and send the request:
```http
POST /paynet/api/v4/create-recurring-payments/ HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/8.4.0
Accept: */*
Content-Type: application/x-www-form-urlencoded
Authorization: OAuth oauth_consumer_key="ErwinTestMerchant",oauth_signature_method="RSA-SHA256",oauth_timestamp="1727178538",oauth_nonce="cdtNANOCATq",oauth_version="1.0",oauth_signature="B5m%2FOQOSBgqWI%2F%2FG3GhZw2kCJZDda7J6fLpOu6wFyBEj60PJp5u1mqBnIufzkkmrSkyZkCT6v12WIhwE%2BWTtJ7Wg%2BRx9cqXPfhk5JhQpnofsVheXpCpftoLvvBTqn8p67WaS%2B6kfzGtGhdXHYVBzIxXDxabnMjMC8u8EtfWsovzTp%2BAYfZKn2H0qH7B62dfUW4PuRCTmy9svbwLhbPULkh3oJ3a1M%2BnRqXIasIrd3WY1MD9lkqUetAtW3xIWnOoMvPZ0wzk2UEbU%2BoZ2KTiA9KO09%2Ffq7OylRhiDpqtz65EMBiKujFFSF42bzYsB1SmPssk09xJoWmsNR9tFZsdx2Hgl7yFZTXhxV3nlSZTGDVZaVe2pPSi8va5W9yTlPMPU5HcNE5MuZ3T9PSEURQvM691UcPSdlJAi8q7B0EhXDzwOlgLV7DsFDtpsXSeXopFpG6uHiNPIjW65p6XFQ31xr4foZCahVeymuIoiXE6uAkHJJ89oHqKsOBnI7xILu2UpflHnl7gn%2BvX9IWdUHx1xEMdBPWdUQRFNllGvT2N8nYrtZe96L%2BfwxarYR2Fh1LtyqwCtEXhQm5jhjpR3NQpqddY3NSd75NUP7zlDQwXCknMQps6uSdng9Uv%2B7IFx3oNUfjVMxp4CGcmEtSxH7Ykx8dX5srNOKLDJT5tyExLLjXk%3D"
Content-Length: 754
Connection: keep-alive
payload=Y2xpZW50LW9yZGVyaWQ7cnBfY2FyZF90eXBlO29yZGVyX2Rlc2M7Zmlyc3QtbmFtZTtsYXN0LW5hbWU7YWRkcmVzczE7Y2l0eTt6aXAtY29kZTtjb3VudHJ5O3N0YXRlO3Bob25lO2VtYWlsO3BlcmlvZDtpbnRlcnZhbDtzdGFydC1kYXRlO2ZpbmlzaC1kYXRlO21heC1yZXBlYXRzLW51bWJlcjthbW91bnQ7YW1vdW50LWZyb207YW1vdW50LXRvO2Ftb3VudC1zZXF1ZW5jZTtjdXJyZW5jeTtjYXJkLXByaW50ZWQtbmFtZTtjcmVkaXQtY2FyZC1udW1iZXI7ZXhwaXJlLW1vbnRoO2V4cGlyZS15ZWFyO2N2djI7cHVycG9zZTtub3RpZnktdXJsO3NzbjtiaXJ0aGRheQ0KMTIzNDU2Nzg5MDtTUkM7O1dpbGw7U3RpbGw7MTIzNCBSZWluO1JlaW1zOzEyMzQ1NjtGUjtCUkU7MTIzNDU2Nzg7d2lsbHN0aWxsQGV4YW1wbGUuY29tO3dlZWs7MTsxNi4wOS4yMDI0OzE3LjA5LjIwMjQ7MTAwMDsxMDs7OztVU0Q7V0lMTCBTVElMTDs0NDU4MjA0NjgxMzg3MDUzOzEyOzIwNDA7MTIzO05vIHB1cnBvc2UgYXQgYWxsO2h0dHA6Ly9leGFtcGxlLmNvbS9jcmVhdGUtbWU7MTIzNDsyMi4wMS4xOTgwDQo%3D
```
#### Success Response Example
> **Note:** The successful response has empty body and HTTP code 200.
```http
HTTP/1.1 200
Server: server
Date: Tue, 24 Sep 2024 09:44:01 GMT
Content-Length: 0
Connection: keep-alive
Keep-Alive: timeout=60
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Strict-Transport-Security: max-age=31536000
```
#### Fail Response Example
> **Note:** The unsuccessful response has empty body and HTTP code 403.
```http
HTTP/1.1 403
Server: server
Date: Wed, 25 Sep 2024 08:45:42 GMT
Content-Length: 0
Connection: keep-alive
Keep-Alive: timeout=60
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
```
### /api/v4/transfer-by-ref
#### Introduction
Deposit to card transfer (D2C) is a money transfer from Connecting Party bank account (Deposit) and Receiver bank card number (PAN) or tokenized card data (Card Reference ID). Deposit to card is initiated through HTTPS POST request by using [URLs](#api-v4-transfer-by-ref-url) and the [parameters](#api-v4-transfer-by-ref-request) specified below. Use [OAuth RSA-SHA256](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md) for authentication.
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|-----------------------------------------------------------------------------------|--------------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v4/transfer-by-ref/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v4/transfer-by-ref/ENDPOINTID |
| https://sandbox.payneteasy.eu/paynet/api/v4/transfer-by-ref/group/ENDPOINTGROUPID | https://gate.payneteasy.eu/paynet/api/v4/transfer-by-ref/group/ENDPOINTGROUPID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded and [Authorization headers](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md).
Parameters marked as Conditional\* can be mandatory for specific integrations. For more information, please contact your manager in Payneteasy.
| Parameter Name | Description | Value |
|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|
| client_orderid | Connecting Party order identifier. | `Necessity`: Required `Type`: String `Lenght`: 128 |
| login | Connecting Party’s login. Must be used as oauth_consumer_key in OAuth Authorization, not included in request as login parameter. | `Necessity`: Required `Type`: String `Lenght`: 20 |
| destination-card-no | Card number of destination card. Mandatory if destination-card-ref-id omitted. For the scenario of payment to a card inside the system, this card will be considered as a destination, and all processing limits, lists and fraud scoring will be applied to it as a destination card. | `Necessity`: Conditional `Type`: String `Lenght`: 16-19 |
| destination-card-ref-id | Card reference id to destination card, obtained at Card Registration step. Mandatory if destination-card-no omitted. For the scenario of payment to a card inside the system, this card will be considered as a destination, and all processing limits, lists and fraud scoring will be applied to it as a destination card. | `Necessity`: Conditional `Type`: Numeric `Lenght`: 20 |
| destination_expire_month | Expire month of destination card. | `Necessity`: Conditional `Type`: String `Lenght`: 1-2 |
| destination_expire_year | Expire year of destination card. | `Necessity`: Conditional `Type`: String `Lenght`: 2-4 |
| amount | Amount to be transferred. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. | `Necessity`: Required `Type`: Numeric `Lenght`: 10 |
| currency | Currency the transaction is charged in (three-letter currency code). Example of valid parameter values are: USD for US Dollar EUR for European Euro. | `Necessity`: Required `Type`: String `Lenght`: 3 |
| order_desc | Order description. | `Necessity`: Required `Type`: String `Lenght`: 64k |
| receiver_identity_document_series | Receiver’s identity document series (e.g. 4 digits for domestic passport). | `Necessity`: Optional `Type`: String `Lenght`: 512 |
| receiver_identity_document_number | Receiver’s identity document number (e.g. 6 digits for domestic passport). | `Necessity`: Optional `Type`: String `Lenght`: 512 |
| receiver_identity_document_id | Receiver’s identity document id. Possible values: 21 for domestic passport or 31 for international passport. | `Necessity`: Optional `Type`: String `Lenght`: 512 |
| receiver_address1 | Receiver’s address. | `Necessity`: Conditional\* `Type`: String `Lenght`: 512 |
| receiver_city | Receiver’s city. | `Necessity`: Conditional\* `Type`: String `Lenght`: 512 |
| receiver_first_name | Receiver first name. | `Necessity`: Required `Type`: String `Lenght`: 128 |
| receiver_middle_name | Receiver middle name. | `Necessity`: Optional `Type`: String `Lenght`: 128 |
| receiver_last_name | Receiver last name. | `Necessity`: Required `Type`: String `Lenght`: 128 |
| receiver_phone | Receiver full international cell phone number, including country code. | `Necessity`: Optional `Type`: String `Lenght`: 128 |
| receiver_resident | Is receiver a resident? | `Necessity`: Optional `Type`: Boolean `Lenght`: true/false |
| ipaddress | Customer’s IP address, included for fraud screening purposes. | `Necessity`: Optional `Type`: String `Lenght`: 45 |
| first_name | Sender first name. | `Necessity`: Optional `Type`: String `Lenght`: 128 |
| middle_name | Sender middle name. | `Necessity`: Optional `Type`: String `Lenght`: 128 |
| last_name | Sender last name. | `Necessity`: Optional `Type`: String `Lenght`: 128 |
| ssn | Last four digits of the Sender’s social security number. | `Necessity`: Optional `Type`: Numeric `Lenght`: 32 |
| birthday | Sender date of birth, in the format MMDDYY. | `Necessity`: Optional `Type`: Numeric `Lenght`: 8 |
| address1 | Sender address line 1. (Please note that in some cases it is not possible to send address length more than 50 characters. Please contact your manager for more details.) | `Necessity`: Optional `Type`: String `Lenght`: 256 |
| city | Sender city. | `Necessity`: Optional `Type`: String `Lenght`: 50 |
| state | Sender’s state. Please see Appendix A for a list of valid state codes. Mandatory for USA, Canada and Australia. | `Necessity`: Optional `Type`: String `Lenght`: 2-3 |
| zip_code | Sender ZIP code. | `Necessity`: Optional `Type`: String `Lenght`: 10 |
| receiver_zip_code | Receiver ZIP code. | `Necessity`: Conditional\* `Type`: String `Lenght`: 10 |
| country | Sender country (two-letter country code). Please see Appendix B for a list of valid country codes. | `Necessity`: Optional `Type`: String `Lenght`: 2 |
| receiver_country_code | Receiver country (two-letter country code). Please see Appendix B for a list of valid country codes. | `Necessity`: Optional `Type`: String `Lenght`: 2 |
| phone | Sender full international phone number, including country code. | `Necessity`: Optional `Type`: String `Lenght`: 15 |
| cell_phone | Sender full international cell phone number, including country code. | `Necessity`: Optional `Type`: String `Lenght`: 15 |
| email | Sender email address. | `Necessity`: Optional `Type`: String `Lenght`: 50 |
| purpose | Destination to where the payment goes. It is useful for the Connecting Parties who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account. Sample values are: +9999999999; mail@example.com etc. This value will be used by fraud monitoring system. | `Necessity`: Optional `Type`: String `Lenght`: 128 |
| server_callback_url | URL, where the transaction status is sent to. Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to server_callback_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of notify_url. If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). | `Necessity`: Optional `Type`: String `Length`: 128 |
| notify_url | URL, where the transaction status is sent to. Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to notify_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of server_callback_url. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. | `Necessity`: Optional `Type`: String `Length`: 128 |
| redirect_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved or declined. See more details at [Statuses](https://doc.payneteasy.com/integration/reference/statuses.html.md). | `Necessity`: Optional `Type`: String `Lenght`: 250 |
| redirect_success_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is approved. | `Necessity`: Optional `Type`: String `Lenght`: 1024 |
| redirect_fail_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is declined or filtered. | `Necessity`: Optional `Type`: String `Lenght`: 1024 |
| merchant_data | Any additional information for this transaction which may be useful in Connecting Party’s external systems, e.g. VIP customer, TV promo campaign lead. Will be returned in Status response and Connecting Party Callback. | `Necessity`: Optional `Type`: String `Lenght`: 64k |
#### Response Parameters
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Response parameter | Description |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be async-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details. |
| paynet-order-id | Order id assigned to the order by Payneteasy. |
| merchant-order-id | Connecting Party order id. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
| error-message | If status is error this parameter contains the reason for decline or error details. |
| error-code | The error code is case of error status. |
#### Request Example
```http
POST /paynet/api/v4/transfer-by-ref/39915 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth oauth_consumer_key="TestMerchant", oauth_nonce="w1rmMzx2Sq2k5Hi7KAZmdhHHD6BygKcE", oauth_signature="rXn0DwLOlaV%2Ft1q3s%2FJdLybJTdxKKN0XeFtyVNZ0U5bG0Qfcc6iyHqQG66Ohb852CYKjhrxvG3wf33RlIQdO9f23OSg91JkdrUgl8QDrMqntC5myWGR1woums%2BMjpV821fAY8AS%2BBByNUKOuC1mwFgLYwr5YinbhjDa6P8aEdHgbf%2FVw5vg9OqjwKxJhSXPGB5mIg7T9gTNXF4n4YTUJA0l%2BWyeGcIjuTSsiCUnbsrNjBOGYc0PlUSuHirwJ0NiKVdHk3qaZrGaEw8SZEq%2F8x0naoaaOXUq%2FkpqPfTJT%2FjTl%2FbGyX1x%2FwTl6EYgIElavHYj2psIGmFnyUk%2FYnaGZHikE00rSf4IkG5Ye2M4hyl7lKQOCXMZMvvGtfvLm0RsAod8o30KuDD5Tw%2BRmDiQNCqN8GeZawHsZipgwZuy2IdZ3sHiot3U6NEt1OVH9TsWDU%2FstfBJOWBBStTRTTh4hn3Zvf5jLuTfTcepKz4CIgdQGGmMmRSz6dcBnkYJaa7VRTh27dz%2BnEuC0laEYAytVuzQA43MvUXNLmAuh9JlmqQquAZwB%2BRFfLPgOj%2FVVsFsqX35UWBYQtWlWdEVc3jWBVxCjEW0s8cAcowlb4R2g4V48HC2Rz3ggfINzP9%2FWtX1nkNnIlzQAeYbMREguYqFrK%2BYK6Lqyu%2BM1jeo6j9CWhhk%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1697442690", oauth_version="1.0"
Content-Length: 805
Content-Type: application/x-www-form-urlencoded
Connection: close
address1=10020Main%20st
&amount=100
&birthday=19820115
&cell_phone=%2B19023384543
&city=Seattle
&client_orderid=34T43R77N
&country=US
¤cy=USD
&destination-card-ref-id=1461819
&card-exp-month=07
&card-exp-year=2028
&email=john.smith%40gmail.com
&first_name=John
&ipaddress=65.153.12.232
&last_name=Smith
&merchant_data=VIP%20customer
&middle_name=M
&order_desc=Test%20Order%20Description
&phone=%2B12063582043
&purpose=user_account1
&receiver_address1=Red%20Sq%2C%201a
&receiver_city=Moscow
&receiver_first_name=Jane
&receiver_identity_document_id=21
&receiver_identity_document_number=222222
&receiver_identity_document_series=1111
&receiver_last_name=Doe
&receiver_middle_name=L
&receiver_phone=%2B79031110022
&receiver_resident=true
&redirect_url=http%3A%2F%2Fwww.example.com%2F
&server_callback_url=https%3A%2F%2Fhttpstat.us%2F200
&ssn=1267&state=WA
&zip_code=98102
```
#### Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Mon, 16 Oct 2023 13:20:25 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 145
type=async-response
&serial-number=00000000-0000-0000-0000-000002ee3a57
&merchant-order-id=34T43R77N
&paynet-order-id=7234671
&end-point-id=39915
```
#### Fail Response Example
```http
HTTP/1.1 200
Server: server
Date: Mon, 16 Oct 2023 07:54:11 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 162
type=validation-error
&serial-number=00000000-0000-0000-0000-000002ee3a4f
&merchant-order-id=34T43R77N
&error-message=Rebill+1461819+was+not+found
&error-code=104
```
#### Open API Collection
Open this method in the OpenAPI Reference
View in OpenAPI
### /api/v4/payout-by-ref/
#### Introduction
Payout By Reference is initiated through HTTPS POST request by using [URLs](#payout-by-ref-api) and the [parameters](#payout-by-ref-parameters) specified below. Use [OAuth RSA-SHA256](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md) for authentication.
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|---------------------------------------------------------------------------------|------------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v4/payout-by-ref/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v4/payout-by-ref/ENDPOINTID |
| https://sandbox.payneteasy.eu/paynet/api/v4/payout-by-ref/group/ENDPOINTGROUPID | https://gate.payneteasy.eu/paynet/api/v4/payout-by-ref/group/ENDPOINTGROUPID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded and [Authorization headers](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md).
> **Note:** Ask Support Manager if Conditional fields are Required for integration.
| Parameter Name | Description | Value |
|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|
| client_orderid | Connecting Party’s order identifier. | `Necessity`: Required `Type`: String `Length`: 128 |
| amount | Amount to be charged. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. | `Necessity`: Required `Type`: Numeric `Length`: 10 |
| currency | Currency the transaction is charged in (three-letter currency code). Sample values are: USD for US Dollar EUR for European Euro. | `Necessity`: Required `Type`: String `Length`: 3 |
| destination-card-ref-id | Card reference id to destination card, obtained at Card Registration step. For the scenario of payment to a card inside the system, this card will be considered as a destination, and all processing limits, lists and fraud scoring will be applied to it as a destination card. | `Necessity`: Required `Type`: Numeric `Length`: 20 |
| order_desc | Brief order description. | `Necessity`: Optional `Type`: String `Length`: 64 |
| ipaddress | Receiver’s IP address (IPv4 or IPv6). | `Necessity`: Conditional `Type`: String `Length`: 7-45 |
| purpose | Payout purpose. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| server_callback_url | URL, where the transaction status is sent to. Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to server_callback_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of notify_url. If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). | `Necessity`: Optional `Type`: String `Length`: 128 |
| notify_url | URL, where the transaction status is sent to. Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to notify_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of server_callback_url. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. | `Necessity`: Optional `Type`: String `Length`: 128 |
| redirect_url | URL, where the Receiver is redirected to upon completion of the transaction. Please note that redirection is performed in any case, no matter whether transaction is approved, declined in any other final [status](https://doc.payneteasy.com/integration/reference/statuses.html.md). Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize server_callback_url or [status API command](https://doc.payneteasy.com/integration/api_v2_status.html.md). Pass https://doc.payneteasy.com if you have no need to return Receiver anywhere. Use either redirect_url or combination of redirect_success_url and redirect_fail_url, not both. | `Necessity`: Optional `Type`: String `Length`: 128 |
| redirect_success_url | URL, where the Receiver is redirected to when transaction status is approved (See [status list](https://doc.payneteasy.com/integration/reference/statuses.html.md)). Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize server_callback_url or [status API command](https://doc.payneteasy.com/integration/api_v2_status.html.md). Otherwise put https://doc.payneteasy.com if there is no need to redirect Receiver anywhere. Use either combination of redirect_success_url and redirect_fail_url or redirect_url, not both. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| redirect_fail_url | URL, where the Receiver is redirected to when transaction status is not approved (See [status list](https://doc.payneteasy.com/integration/reference/statuses.html.md)). Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize server_callback_url or [status API command](https://doc.payneteasy.com/integration/api_v2_status.html.md). Pass https://doc.payneteasy.com if there is no need to redirect Receiver anywhere. Use either combination of redirect_fail_url and redirect_success_url or redirect_url, not both. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| account_number | Account Number. | `Necessity`: Conditional `Type`: String `Length`: 24 |
| account_name | Bank account. | `Necessity`: Optional `Type`: String `Length`: 128 |
| ewallet_type | Type of e-wallet. | `Necessity`: Conditional `Type`: String `Length`: 64 |
| ewallet_wallet | E-wallet ID. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| crypto_wallet_address | Address of crypto wallet. | `Necessity`: Conditional `Type`: String `Length`: 64 |
| bank_name | Bank Name. | `Necessity`: Conditional `Type`: String `Length`: 255 |
| bank_branch | Bank Branch Name. | `Necessity`: Conditional `Type`: String `Length`: 255 |
| bank_code | Bank code. | `Necessity`: Conditional `Type`: String `Length`: 32 |
| bank_city | Bank city. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| bank_address1 | Bank address. | `Necessity`: Conditional `Type`: String `Length`: 255 |
| bank_zip_code | Bank postal ZIP code. | `Necessity`: Conditional `Type`: String `Length`: 255 |
| bank_province | Bank province. | `Necessity`: Conditional `Type`: String `Length`: 255 |
| bank_area | Bank area. | `Necessity`: Conditional `Type`: String `Length`: 255 |
| routing_number | Routing number used to identify specific bank branches in China. | `Necessity`: Conditional `Type`: String `Length`: 16 |
| legal_person_name | Name on the legal document. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| legal_person_document_number | Number of legal document. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| receiver_first_name | Receiver first name, also can be sent as first_name. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| receiver_last_name | Receiver last name, also can be sent as last_name. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| receiver_birthday | Receiver birthday, also can be sent as birthday. | `Necessity`: Conditional `Type`: Numeric `Length`: 30 |
| receiver_country_code | Receiver country code, also can be sent as country. | `Necessity`: Conditional `Type`: String `Length`: 3 |
| receiver_state | Receiver state, should be provided for countries that have states (USA, Canada, Australia), also can be sent as state. | `Necessity`: Conditional `Type`: String `Length`: 4 |
| receiver_city | Receiver city, also can be sent as city. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| receiver_zip_code | Receiver zip code, also can be sent as zip_code. | `Necessity`: Conditional `Type`: Numeric `Length`: 32 |
| receiver_address1 | Receiver address, also can be sent as address1. | `Necessity`: Conditional `Type`: String `Length`: 256 |
| receiver_phone | Receiver phone, also can be sent as phone. | `Necessity`: Conditional `Type`: Numeric `Length`: 128 |
| receiver_email | Receiver E-mail, also can be sent as email. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| receiver_identity_document_id | Receiver identity document identifier, also can be sent as identity_document_id. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| receiver_identity_document_number | Receiver identity document number, also can be sent as identity_document_number. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| merchant_data | Any additional information for this transaction which may be useful in Connecting Party’s external systems, e.g. VIP customer, TV promo campaign lead. Will be returned in Status response and Connecting Party Callback. | `Necessity`: Optional `Type`: String `Length`: 64k |
| bank_bic | BIC of the receiver’s bank. | `Necessity`: Optional `Type`: String `Length`: 128 |
| receiver_inn | Receiver’s INN. | `Necessity`: Optional `Type`: String `Length`: 128 |
| customer_level | Customer level in CMS system | `Necessity`: Optional `Type`: Varchar `Length`: 32 |
| customer_id | Customer ID in CMS system. Required if transaction goes via CMS (Payment Gateway mode) | `Necessity`: Optional `Type`: Int `Length`: 10 |
| merchant_customer_identifier | Merchant Customer ID in CMS system. Required if transaction goes via CMS (CRM mode) | `Necessity`: Optional `Type`: Varchar `Length`: 64 |
| card-ref-id | Card reference ID used in subsequent recurring payments. Card reference ID can be created with [v4 tokenization request](https://doc.payneteasy.com/integration/api_v4_create-card-ref.html.md) or [v2 tokenization request](https://doc.payneteasy.com/integration/api_v2_create-card-ref.html.md). | `Necessity`: Conditional `Type`: Long |
#### Response Parameters
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Payout Request Parameters | Description |
|-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be async-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details |
| paynet-order-id | Order id assigned to the order by Payneteasy. |
| merchant-order-id | Connecting Party order id. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
| error-message | If status is error this parameter contains the reason for decline or error details. |
| error-code | The error code is case of error status. |
#### Request Example
```http
POST /paynet/api/v4/payout-by-ref/121799 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/8.4.0
Accept: */*
Authorization: OAuth oauth_consumer_key="ErwinTestMerchant", oauth_nonce="8qsDrhiDelGHlxY01aDjCh44u7isXJjL", oauth_signature="WpbNcRxNSDW%2BdJgftRc%2BAN0oe8KAP4CNpUkxjxStFYZEU9Vo%2F7uk9dSKEG%2B76C%2FdlzemILaRmikQqZg93ZK1cibT8zy97uYVDdWVmY2obDSOVb8UipGjt2KFUyKr4awHW9xH%2BTzbR%2FMXwm3y%2Fx2RotElZWxumsL37P5Q%2BCquoAGcO6jjkvkkSH9P4lBYKSmwhfqD4O%2Br8FB3exzNzl2FFBTwLp4ch2G9Cis5a0CkVrpjDB%2FbbbrOutbNPZYhtH45rNz91QAbpvNJ91XjVwxiCm4lCldIO66gF73GQNSFKVG1mstc%2B941Dj1bVhXWQQW%2F9TyPiXfWGP8szg18rwsTHbj1zKCRIaw%2FqVbrOBPhbo%2BJjGMZp2hB1ei0%2FUPIkjeIZkWD2NgJRQEniJfjU7AlILs91augm50fPwWR5JiOuE5uSvwM6VWgXMpYe4USb819ZAK%2BFYTRI%2BenrycFZHmY%2BafOlaOHFtpnbn8FsrzzNbOvGXmXCt2xXAQTaORqMeLRRtkD3DY4rJa8qeO0zYnmT4ZhKsFZjImDdonA3WTG8G7awP9W0RKhHlUGwGaugRWbdPjSbGMhAzs58Y9ptvExr6GwAHhJU1RbzfWL4wCzVbH8%2BAC6I0OrkB13tw2eXP4yIPtEC7iGu%2FkElGz4OrwFEU6cUcEDpeEOmA2%2Fe%2BZFK0w%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1721975900", oauth_version="1.0"
Content-Length: 74
Content-Type: application/x-www-form-urlencoded
Connection: keep-alive
amount=10.42
&client_orderid=1
¤cy=USD
&destination-card-ref-id=1461897
```
#### Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Fri, 26 Jul 2024 06:39:23 GMT
Content-Type: text/html;charset=utf-8
Connection: keep-alive
Keep-Alive: timeout=60
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 138
type=async-response
&serial-number=00000000-0000-0000-0000-000002f36e41
&merchant-order-id=1
&paynet-order-id=7363634
&end-point-id=121799
```
#### Fail Response Example
```http
HTTP/1.1 200
Server: server
Date: Fri, 26 Jul 2024 06:42:43 GMT
Content-Type: text/html;charset=utf-8
Connection: keep-alive
Keep-Alive: timeout=60
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 170
type=validation-error
&serial-number=00000000-0000-0000-0000-000002f36e42
&error-message=Project+with+currency+USD+does+not+apply+request+with+currency+AZN
&error-code=16
```
### /api/v4/payout
#### Introduction
Payout is initiated through HTTPS POST request by using [URLs](#payout-apis) and the [parameters](#payout-parameters) specified below. Use [OAuth RSA-SHA256](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md) for authentication.
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|--------------------------------------------------------------------------|-----------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v4/payout/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v4/payout/ENDPOINTID |
| https://sandbox.payneteasy.eu/paynet/api/v4/payout/group/ENDPOINTGROUPID | https://gate.payneteasy.eu/paynet/api/v4/payout/group/ENDPOINTGROUPID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded and [Authorization headers](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md).
| Parameter Name | Description | Value |
|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|
| client_orderid | Connecting Party’s order identifier. | `Necessity`: Required `Type`: String `Length`: 128 |
| amount | Amount to be charged. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. | `Necessity`: Required `Type`: Numeric `Length`: 10 |
| currency | Currency the transaction is charged in (three-letter currency code). Sample values are: USD for US Dollar EUR for European Euro. | `Necessity`: Required `Type`: String `Length`: 3 |
| order_desc | Brief order description. | `Necessity`: Optional `Type`: String `Length`: 64 |
| ipaddress | Receiver’s IP address (IPv4 or IPv6). | `Necessity`: Conditional `Type`: String `Length`: 7-45 |
| purpose | Payout purpose. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| server_callback_url | URL, where the transaction status is sent to. Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to server_callback_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of notify_url. If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). | `Necessity`: Optional `Type`: String `Length`: 1024 |
| notify_url | URL, where the transaction status is sent to. Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to notify_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of server_callback_url. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. | `Necessity`: Optional `Type`: String `Length`: 128 |
| redirect_url | URL, where the Receiver is redirected to upon completion of the transaction. Please note that redirection is performed in any case, no matter whether transaction is approved, declined in any other final [status](https://doc.payneteasy.com/integration/reference/statuses.html.md). Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize server_callback_url or [status API command](https://doc.payneteasy.com/integration/api_v2_status.html.md). Pass https://doc.payneteasy.com if you have no need to return Receiver anywhere. Use either redirect_url or combination of redirect_success_url and redirect_fail_url, not both. | `Necessity`: Optional `Type`: String `Length`: 128 |
| redirect_success_url | URL, where the Receiver is redirected to when transaction status is approved (See [status list](https://doc.payneteasy.com/integration/reference/statuses.html.md)). Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize server_callback_url or [status API command](https://doc.payneteasy.com/integration/api_v2_status.html.md). Otherwise put https://doc.payneteasy.com if there is no need to redirect Receiver anywhere. Use either combination of redirect_success_url and redirect_fail_url or redirect_url, not both. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| redirect_fail_url | URL, where the Receiver is redirected to when transaction status is not approved (See [status list](https://doc.payneteasy.com/integration/reference/statuses.html.md)). Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize server_callback_url or [status API command](https://doc.payneteasy.com/integration/api_v2_status.html.md). Pass https://doc.payneteasy.com if there is no need to redirect Receiver anywhere. Use either combination of redirect_fail_url and redirect_success_url or redirect_url, not both. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| credit_card_number | Customer’s credit card number. **Note: For the scenario of payment to a card inside the system, this card will be considered as a source, and all processing limits, lists and fraud scoring will be applied to it as a source card.** | `Necessity`: Conditional `Type`: Numeric `Length`: 20 |
| card_printed_name | Customer’s full name, as printed on the card. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| expire_month | Credit card expiration month. | `Necessity`: Conditional `Type`: Numeric `Length`: 2 |
| expire_year | Credit card expiration year. | `Necessity`: Conditional `Type`: Numeric `Length`: 4 |
| cvv2 | Receiver’s CVV2 code. CVV2 (Card Verification Value) is a three- or four-digit number AFTER the credit card number in the signature area of the card. | `Necessity`: Conditional `Type`: Numeric `Length`: 3-4 |
| account_number | Account Number. | `Necessity`: Conditional `Type`: String `Length`: 32 |
| account_name | Bank account. | `Necessity`: Optional `Type`: String `Length`: 128 |
| ewallet_type | Type of e-wallet. | `Necessity`: Conditional `Type`: String `Length`: 64 |
| ewallet_wallet | E-wallet ID. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| crypto_wallet_address | Address of crypto wallet. | `Necessity`: Conditional `Type`: String `Length`: 64 |
| bank_name | Bank Name. | `Necessity`: Conditional `Type`: String `Length`: 255 |
| bank_branch | Bank Branch Name. | `Necessity`: Conditional `Type`: String `Length`: 255 |
| bank_code | Bank code. | `Necessity`: Conditional `Type`: String `Length`: 32 |
| bank_city | Bank city. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| bank_address1 | Bank address. | `Necessity`: Conditional `Type`: String `Length`: 255 |
| bank_zip_code | Bank postal ZIP code. | `Necessity`: Conditional `Type`: String `Length`: 255 |
| bank_province | Bank province. | `Necessity`: Conditional `Type`: String `Length`: 255 |
| bank_area | Bank area. | `Necessity`: Conditional `Type`: String `Length`: 255 |
| routing_number | Routing number used to identify specific bank branches in China. | `Necessity`: Conditional `Type`: String `Length`: 16 |
| legal_person_name | Name on the legal document. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| legal_person_document_number | Number of legal document. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| receiver_first_name | Receiver first name, also can be sent as first_name. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| receiver_last_name | Receiver last name, also can be sent as last_name. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| receiver_middle_name | Receiver middle name, also can be sent as middle_name. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| receiver_birthday | Receiver birthday, also can be sent as birthday. | `Necessity`: Conditional `Type`: Numeric `Length`: 30 |
| receiver_country_code | Receiver country code, also can be sent as country. | `Necessity`: Conditional `Type`: String `Length`: 3 |
| receiver_state | Receiver state, should be provided for countries that have states (USA, Canada, Australia), also can be sent as state. | `Necessity`: Conditional `Type`: String `Length`: 4 |
| receiver_city | Receiver city, also can be sent as city. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| receiver_zip_code | Receiver zip code, also can be sent as zip_code. | `Necessity`: Conditional `Type`: Numeric `Length`: 32 |
| receiver_address1 | Receiver address, also can be sent as address1. | `Necessity`: Conditional `Type`: String `Length`: 256 |
| receiver_phone | Receiver phone, also can be sent as phone. | `Necessity`: Conditional `Type`: Numeric `Length`: 128 |
| receiver_email | Receiver E-mail, also can be sent as email. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| receiver_identity_document_id | Receiver identity document identifier, also can be sent as identity_document_id. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| receiver_identity_document_number | Receiver identity document number, also can be sent as identity_document_number. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| merchant_data | Any additional information for this transaction which may be useful in Connecting Party’s external systems, e.g. VIP customer, TV promo campaign lead. Will be returned in Status response and Connecting Party Callback. | `Necessity`: Optional `Type`: String `Length`: 64k |
| bank_bic | BIC of the receiver’s bank. | `Necessity`: Optional `Type`: String `Length`: 128 |
| receiver_inn | Receiver’s INN. | `Necessity`: Optional `Type`: String `Length`: 128 |
| customer_level | Customer level in CMS system | `Necessity`: Optional `Type`: Varchar `Length`: 32 |
| customer_id | Customer ID in CMS system. Required if transaction goes via CMS (Payment Gateway mode) | `Necessity`: Optional `Type`: Int `Length`: 10 |
| merchant_customer_identifier | Merchant Customer ID in CMS system. Required if transaction goes via CMS (CRM mode) | `Necessity`: Optional `Type`: Varchar `Length`: 64 |
| card_recurring_payment_id | Payer’s tokenized cardholder’s data ID, referred as Recurring Payment ID (RPI). Send either card_recurring_payment_id or combination of credit_card_number, card_printed_name, expire_month and expire_year, not all. To create card_recurring_payment_id see [/api/v4/create-card-ref](https://doc.payneteasy.com/integration/api_v4_create-card-ref.html.md). **Note: For the scenario of payment to a card inside the system, this card will be considered as a source, and all processing limits, lists and fraud scoring will be applied to it as a source card.** | `Necessity`: Conditional `Type`: Long |
| recurring-payment-id | Recurring Payment ID can be sent instead of cardholder data. Customer Data can be updated via [/api/v4/update-recurring-payment/](https://doc.payneteasy.com/integration/api_v4_update-recurring-payment.html.md). Recurring Payment ID creation is initiated through HTTPS POST request by using [URLs](https://doc.payneteasy.com/integration/api_v4_create-card-ref.html.md) and the [parameters](https://doc.payneteasy.com/integration/api_v4_create-card-ref.html.md) specified below. Use [OAuth RSA-SHA256](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md) for authentication. | `Necessity`: Conditional `Type`: Long |
\* Ask Support Manager if Conditional fields are Required for integration.
#### Response Parameters
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Payout Response Parameters | Description |
|------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be async-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details |
| paynet-order-id | Order id assigned to the order by Payneteasy. |
| merchant-order-id | Connecting Party order id. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
| error-message | If status is error this parameter contains the reason for decline or error details. |
| error-code | The error code is case of error status. |
#### Request Example
```http
POST /paynet/api/v4/payout/39915 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth oauth_consumer_key="TestMerchant", oauth_nonce="b5E31Tw6SVjauE29uOf2jOLnuUSXmVdE", oauth_signature="WrW79JHNUVwDRhCGWQYgaN6xmJXpQxy8XSNyCOL6b2Wyf7V5BWGMe2TZa1bjC9ZeO0Q3FcQxeGGHv0%2F7hsMAsJNQEET321VNsbDwao2Ep%2Bp7eoYiGYrVveSrSW1diCrBf3AJYJZM0PTJ67Sl8XyeTVBHT4kpC5qBu3xDQ3aFfKnmRTmn9fiVsYsYu3DQrsHM1K9uAoltGt3Muz0kCDZ3MWNGrNqtdpWuar8HRQD3kckcPjuN9D6VrSuQm9eLx27G%2FvkiP%2BZ44i8ghIUp61NWSrJ4Ky69JiZ%2FoaVVmUTEaanc%2F%2B%2BQT6jBwWy%2Bb%2FTLUrxtSakeNfcjn1JVwRf4aCX2fhyG5ozH%2BjiXF6eRb83WVqBUAwykSq35pLU3Vmua3pKMKAJK1ZRDZdjGrT50KJg5tBniC4JFzdQqjQf%2FhFnDYodfIK3S2qZo%2FD3Bmlya46iEcK6SAQdNBBQue3E5Qi8FEHYrY1o7K8wDyzT1QzqqHF%2BQdmXcElSGu9ge0Y655%2BbGtXhnsUWnKEO0NGqErvAwzm7yUg0e5QWHVf505aE7pr5K4z%2Fzj7AvkuD7R1savqam%2BnnuSfq1E%2BnnnN7mTcC0g18Sr38vdTshcGq99YW3xWKc%2FpuooZYdYa5A6u46o%2BREZSTCD2XexcV49%2F9eVn3xdoTXYq4NISJSY8U7ThKnr0g%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1677831012", oauth_version="1.0"
Content-Length: 150
Content-Type: application/x-www-form-urlencoded
Connection: close
account_name=1234
&account_number=1234
&amount=10.42
&client_orderid=1
¤cy=USD
&routing_number=15
&server_callback_url=https%3A%2F%2Fhttpstat.us%2F200
```
#### Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Fri, 03 Mar 2023 08:10:34 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 137
type=async-response
&serial-number=00000000-0000-0000-0000-000002e2c322
&merchant-order-id=1
&paynet-order-id=6982864
&end-point-id=39915
```
#### Fail Response Example
```http
HTTP/1.1 403 Forbidden
Server: server
Date: Thu, 25 Aug 2022 06:50:16 GMT
Content-Type: text/html
Content-Length: 735
Connection: close
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
403
Access is denied
```
#### Test Scenario
Different Payout transaction statuses can be received on sandbox depending on the account_number value passed in Payout request.
Testing account_number values:
> * account_number = 1234567890 to get APPROVED
> * account_number = 0987654321 to get DECLINED
> * account_number = 1987654321 to get PROCESSOR_INTERNAL_ERROR
#### Open API Collection
Open this method in the OpenAPI Reference
View in OpenAPI
### /api/v4/process-recurring-payment
#### Introduction
If request is accepted with no errors, the Payment Gateway finds the recurring payment profile by the provided recurring-payment-id and initiates a new recurring transaction using the payment data saved in this profile.
Process recurring payment is initiated through HTTPS POST request by using [URLs](#api-v4-process-recurring-payment-request-url) and the [parameters](#api-v4-process-recurring-payment-request-parameters) specified below. Use [OAuth RSA-SHA256](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md) for authentication.
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|----------------------------------------------------------------------------------|-------------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v4/process-recurring-payment/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v4/process-recurring-payment/ENDPOINTID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded and [Authorization headers](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md).
| Parameter Name | Description | Value |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| client-orderid | Connecting Party order ID. | `Necessity`: Required `Type`: String `Length`: 128 |
| recurring-payment-id | Recurring ID assigned to the order by QA. | `Necessity`: Required `Type`: String `Length`: 10 |
| amount | Amount of currency must be the same as currency on the project assigned. Upon reaching finish date, Recurring payment will go into stop status. Supported for SRC and DST type. Required if amount-from and amount-to or amount-sequence are not used. | `Necessity`: Conditional `Type`: Numeric `Length`: 10 |
#### Response Parameters
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Response Parameters | Description |
|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. Example: process-recurring-payment-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details. |
| status | If request is accepted, this parameter has processing value. This is not a transaction status. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
#### Request Example
```http
POST /paynet/api/v4/process-recurring-payment/ HTTP/1.1
User-Agent: curl/8.4.0
Accept: */*
Authorization: OAuth oauth_consumer_key="ErwinTestMerchant", oauth_nonce="XGsxKTfd4uiaQKOSyXkHQwKxFqLCEKRz", oauth_signature="KX7KEjFUEJo8rLJ2PvusGDlu5cxqMm%2BU%2Bn%2F1KxH18QUeZ57QghfnXyiXKCxwAr76uxMk9X10QL8YI4kuEHVmxThIomtIZML3yRLESneHNqZzlwXvTSG5o%2B7DTSdAeNGZ40PIbF4XAUzwp%2FQbpYGWBS4Yk36%2BPQbziJlsFa21gRo7e03fizxPEIYi1algEqOT5uu%2F07Yci6NsSyGGMGo4vyDhqPMLuDcaTeO%2Fzr51RfRa4jh2bT4tUriZLVrjYP0AJeHGlZdosTkqEyVAz5Q5yD67xmjUGlW4luezOWdR70wrfQ8JZ7QuXzueAb9TqyZfi%2BvCD4MrhXG299ujWUUtZ%2F8qi09p%2F7GmBiFSud7wgMjPGOC%2BijBEFIpsfiBFzd6%2FX7MBLAdTpHXrExT2C71dJysde31isAMVuIIuvXogY7YE0ZttWY1oYqcWDNSWXsUx5pQTjbBf1vyJB3CqtAFVFi6LwckqsYTAXkxfp%2B2IgFFhadEvf35XzFPv%2FEjsTqRLJuPYBa85mK9vaY7WJRtX89TjSdEPulFnz1EEFg5KHe5WxVp9GFw2XqLneqBu%2FwGAGg3NXRumBMHK3E%2Bh96cVdU5b3AkqVjS2Q36jpQtAhUIIGYyT02n4W9avhw2cHCJzErqGjALHJjkFQD1bhDRKyTm1Fqeh%2BplDaPwDKjy5EHY%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1721316898", oauth_version="1.0"
Content-Length: 407
Content-Type: application/x-www-form-urlencoded
Connection: keep-alive
recurring-payment-id=1492124
&amount=10
&client-orderid=1575634981130
```
#### Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Thu, 18 Jul 2024 15:35:46 GMT
Content-Type: text/html;charset=utf-8
Connection: keep-alive
Keep-Alive: timeout=60
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 110
type=process-recurring-payment-response
&serial-number=00000000-0000-0000-0000-000002f36d8d
&status=processing
```
#### Fail Response Example
```http
HTTP/1.1 500
Server: server
Date: Thu, 18 Jul 2024 15:39:05 GMT
Content-Length: 61
Connection: keep-alive
Keep-Alive: timeout=60
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Internal server error [b2a06c5a-c770-4c01-b32c-e4fcb1da4cd6]
```
#### Open API Collection
Open this method in the OpenAPI Reference
View in OpenAPI
### /api/v4/process-recurring-payments
#### Introduction
If request is accepted with no errors, the Payment Gateway finds the recurring payment profiles for each provided recurring-payment-id and initiates new recurring transactions using the payment data saved in each profile.
Process recurring payment Multiple is initiated through HTTPS POST request by using [URLs](#api-v4-process-recurring-payments-request-url) and the [parameters](#api-v4-process-recurring-payments-request-parameters) specified below. Use [OAuth RSA-SHA256](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md) for authentication.
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|-----------------------------------------------------------------------------------|--------------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v4/process-recurring-payments/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v4/process-recurring-payments/ENDPOINTID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded and [Authorization headers](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md).
Below is a description of each parameter that can be included in the CSV and added to payload parameter which will be used in the request.
| CSV Parameter Name | Description | Value |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| client-orderid | Connecting Party order ID. | `Necessity`: Required `Type`: String `Length`: 128 |
| recurring-payment-id | Recurring ID assigned to the order by QA. | `Necessity`: Required `Type`: String `Length`: 10 |
| amount | Amount of currency must be the same as currency on the project assigned. Upon reaching finish date, Recurring payment will go into stop status. Supported for SRC and DST type. Required if amount-from and amount-to or amount-sequence are not used. | `Necessity`: Conditional `Type`: Numeric `Length`: 10 |
#### Response Parameters
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Response Parameters | Description |
|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. Example: process-recurring-payment-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details. Multiple error codes may be received: 200, 403, and 500. For the 500 error code, an additional error ID will be returned. |
| status | See [Status List](https://doc.payneteasy.com/integration/reference/statuses.html.md) for details |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Merchant |
#### Request Example
**Step 1.** Create a CSV with the provided structure:
```http
"client-orderid";"recurring-payment-id";"amount"
```
**Step 2.** Encode CSV to base64 with the following command:
```bash
base64 process-recurring-payments-example.csv
```
**Step 3**. Assign the base64 encoded value to payload parameter and send the request:
```http
POST /paynet/api/v4/process-recurring-payments/ HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/8.4.0
Accept: */*
Content-Type: application/x-www-form-urlencoded
Authorization: OAuth oauth_consumer_key="ErwinTestMerchant",oauth_signature_method="RSA-SHA256",oauth_timestamp="1727177782",oauth_nonce="Js4dwXkF8eI",oauth_version="1.0",oauth_signature="EGLiLoJJsZzZ4LgTdexkExuNCeyJEkSYuQwsrLMTvucJiIoG2rXL%2FaIkwnXwY6ncXS%2BopSYszmvAE1KnR316YxfyPzvgwO7LkrCE9r80yEfYuGOjwdB7fqvCyYtPqylS7MJ0%2BJM1EIowuWkiwURLqU3mG4J00t1Kl7CRrsjT9nwKoj8mRrljb1St3rAh8bJ7SsdKKQwir1Va6t0cuVMxjsUHJqCtztoCXAPj%2BRz4UKrjbQnwNvJ1MfOnTyeRXTAJgGg7XwctumcG5W2vfuKICwEUQ9S95jxXIci%2FmHuA8gkV7DmfolT1CnxDYzhJwvspvg9BP%2FFVxOGjUTEKDwNhCX5BB3B6EUkyEFI79V8tAtUdUy%2FzRmChPA%2FYvyBky8egkVXoKgwoUHiTQ5ITEhbzCTLjuVm9J%2FEwqVHQkwPbn6T5aTcvQBoMkDtZ70qm7J73wPKuN%2B7S%2Fi0SBc6gwGyu6G%2FfXYu%2BvDY8Ihtd6HRUC59sUYQ6D3tVbh8CE4W9tF1UiXCAoPehdBga%2BR6WUq%2FnD%2FRFrBDZ2Y%2Bz%2FMGhjQHBNZu%2B5z4JjNn7QusHpO1ZwvrI1kSlK79toVOiwVX%2FcP4H5M20s5EPjvSrcc2tnqQSUUOLFGyRFObQgs7kmBxUjEMXbVh9QXlIBdSvy4S8PkFnqYjVLh2aNgTpw%2BgB8RrZ1MY%3D"
Content-Length: 888
Connection: keep-alive
payload=cmVjdXJyaW5nLXBheW1lbnQtaWQ7Y2xpZW50LW9yZGVyaWQ7cGF5bWVudC1kZXNjcmlwdGlvbjtmaXJzdC1uYW1lO2xhc3QtbmFtZTthZGRyZXNzMTtjaXR5O3ppcC1jb2RlO2NvdW50cnk7c3RhdGU7cGhvbmU7ZW1haWw7Y3VzdG9tZXItaXA7YW1vdW50O2N1cnJlbmN5O3B1cnBvc2U7bm90aWZ5LXVybDtzc247YmlydGhkYXkNCjE0OTIyODY7MTIzNDU2Nzg5MDtPdXIgZ29vZHM7Sm9objtTbWl0aDsxMjM0IFBlYWNlIHN0cmVldDtDaGljYWdvOzEyMzQ1NjtVUztJTDsxMjM0NTY3ODtqb2huLnNtaXRoQGV4YW1wbGUuY29tOzEuMi4zLjc7MTA7VVNEO05vIHB1cnBvc2UgYXQgYWxsO2h0dHA6Ly9leGFtcGxlLmNvbS9wcm9jZXNzLW1lOzEyMzQ7MDIuMDEuMTk4MA0K
```
#### Success Response Example
> **Note:** The successful response has empty body and HTTP code 200.
```http
HTTP/1.1 200
Server: server
Date: Tue, 24 Sep 2024 09:47:01 GMT
Content-Length: 0
Connection: keep-alive
Keep-Alive: timeout=60
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Strict-Transport-Security: max-age=31536000
```
#### Fail Response Example
> **Note:** The unsuccessful response has empty body and HTTP code 403.
```http
HTTP/1.1 403
Server: server
Date: Wed, 25 Sep 2024 08:46:12 GMT
Content-Length: 0
Connection: keep-alive
Keep-Alive: timeout=60
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
```
### /api/v4/status
#### Introduction
To make an order status request one have to send an HTTPS POST request to the [URLs](#status-request-v4-url) and the [parameters](https://doc.payneteasy.com/integration/api_v2_status.html.md) specified below. Use [RSA-SHA256](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md) for authentication. See [Statuses](https://doc.payneteasy.com/integration/reference/statuses.html.md).
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|--------------------------------------------------------------------------|-----------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v4/status/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v4/status/ENDPOINTID |
| https://sandbox.payneteasy.eu/paynet/api/v4/status/group/ENDPOINTGROUPID | https://gate.payneteasy.eu/paynet/api/v4/status/group/ENDPOINTGROUPID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded and [Authorization headers](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md).
| Parameter Name | Description | Necessity |
|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|
| login | Connecting Party login name. | Mandatory |
| client_orderid | Unique order identifier assigned by Connecting Party. | Mandatory |
| orderid | Order id assigned to the order by Payneteasy. | Conditional |
| by-request-sn | Serial number assigned to the specific request by Payneteasy. If this field exist in status request, status response return for this specific request. Include this parameter to get the status request with the particular transaction stage (can be used in specific cases). To get the latest transaction status, don’t include this parameter in status request. | Optional |
In most common cases, the best option is to include both client_orderid and orderid parameters to status request. Order status can be requested with only client_orderid if it’s unique to Connecting Party and orderid is not received. If orderid is not received in response, but this response contains an error, see the received error message to get the information why transaction was not created in the system.
#### Response Parameters
The same API command for status request is used in multiple Use-Cases, therefore some of the mentioned response parameters might not be present for specific case. Below is the full list of possible parameters.
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
\* - these parameters are not defined by default. Please contact tech support to include these fields in callback.
| Status Response Parameter | Description |
|-------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be status-response. |
| status | See [Status List](https://doc.payneteasy.com/integration/reference/statuses.html.md) for details. |
| amount | Actual transaction amount. This value can be changed during the transaction flow. |
| currency | Currency the transaction is charged in (three-letter currency code). Example of valid parameter values are: USD for US Dollar EUR for European Euro. |
| paynet-order-id | Order id assigned to the order by gate.payneteasy.eu. |
| merchant-order-id | Connecting Party order id. |
| phone | Payer’s full international phone number, including country code. |
| html | HTML code of 3DS authorization form, encoded in application/x-www-form-urlencoded MIME format. Connecting Party must decode this parameter before showing the form to the Payer. gate.payneteasy.eu System returns the following response parameters when it gets 3DS authorization form from the Issuer Bank. It contains auth form HTML code which must be passed through without any changes to the client’s browser. This parameter exists and has value only when the redirection HTML is already available. For non-3DS this never happens. For 3DS HTML has value after some short time after the processing has been started. |
| redirect-to | For 3DS authorization Connecting Party can redirect the Payer to URL provided in this parameter instead of rendering the page provided in html parameter. The redirect-to parameter is returned only if the html parameter is returned. Connecting Party should use GET HTTP method to redirect. This parameter must be used to work with 3DS 2.0. |
| serial-number | Unique number assigned by gate.payneteasy.eu server to particular request from the Connecting Party. |
| last-four-digits | Last four digits of Payer bank card number. |
| dest-last-four-digits | Last four digits of customer credit card number. Relevant only for transfer transactions. |
| bin | Bank BIN of Payer bank card number. |
| card-type | Type of Payer bank card (VISA, MASTERCARD, etc). |
| gate-partial-reversal | Processing gate support partial reversal (enabled or disabled). |
| gate-partial-capture | Processing gate support partial capture (enabled or disabled). |
| transaction-type | Transaction type (sale, reversal, capture, preauth). |
| processor-rrn | Bank Receiver Registration Number. |
| processor-tx-id | Acquirer transaction identifier. |
| receipt-id | Electronic link to receipt https://gate.payneteasy.eu/paynet/view-receipt/ENDPOINTID/receipt-id/. |
| name | Payer’s name. |
| card-ref-id | Card reference ID used in subsequent recurrent payments. Relevant only if card-ref-id was created for initial transaction. |
| cardholder-name | Cardholder’s name. |
| card-exp-month | Bank card expiration month. |
| card-exp-year | Bank card expiration year. |
| card-hash-id | Unique card identifier to use for loyalty programs or fraud checks. |
| card-country-alpha-three-code | Three letter country code of source card issuer. See [Country and State Codes](https://doc.payneteasy.com/integration/reference/country_codes.html.md) for details. |
| destination-card-country-alpha-three-code | Three letter country code of destination card issuer. See [Country and State Codes](https://doc.payneteasy.com/integration/reference/country_codes.html.md) for details. |
| dest-bin | Bank BIN of customer credit card number. |
| dest-card-type | Type of customer credit card (VISA, MASTERCARD, etc). |
| dest-bank-name | Bank name by customer card BIN. |
| destination-hash-id | Unique card identifier to use for loyalty programs or fraud checks. Relevant only for transfer transactions. |
| destination-card-hash-id | Unique card identifier to use for loyalty programs or fraud checks. |
| first-name | Payer’s first name. |
| last-name | Payer’s last name. |
| email | Payer’s e-mail. |
| country \* | Payer’s country (two-letter country code). Please see [Country and State Codes](https://doc.payneteasy.com/integration/reference/country_codes.html.md) for a list of valid country codes. |
| state \* | Payer’s state . Please see [Country and State Codes](https://doc.payneteasy.com/integration/reference/country_codes.html.md) for a list of valid state codes. Mandatory for USA, Canada and Australia. |
| city \* | Payer’s city. |
| zip_code \* | Payer’s ZIP code. |
| address1 \* | Payer’s address line 1. |
| purpose | Destination to where the payment goes. It is useful for Connecting Party who let their payers to top up their accounts with bank card (Mobile phone accounts, game accounts etc.). Sample values are: +9999999999; mail@example.com etc. This value can be used by the fraud monitoring system. |
| bank-name | Bank name by Payer card BIN. |
| terminal-id | Acquirer terminal identifier to show in receipt. |
| paynet-processing-date | Acquirer transaction processing date. |
| approval-code | Bank approval code. |
| order-stage | The current stage of the transaction processing. See [Order Stage](https://doc.payneteasy.com/integration/reference/order_stage.html.md) for details. |
| total-reversal-amount | Total amount of processed reversals. Relevant only for reversal transactions. |
| reversal-amount | The amount of the last processed reversal. Relevant only for reversal transactions. |
| auth-response-code | Response code used in Iso8583 protocol. Only returned in specific cases. |
| acquirer-processing-date | Acquirer transaction processing date. |
| processor-auth-credit-code | Approval credit code. Only returned in specific cases. |
| processor-credit-rrn | Retrieval Reference Number for credit transaction. |
| processor-credit-arn | Acquirer card reference number for credit transaction. |
| processor-debit-arn | Acquirer card reference number for debit transaction. |
| loyalty-balance | The current bonuses balance of the loyalty program for current operation. if available. |
| loyalty-message | The message from the loyalty program. if available. |
| loyalty-bonus | The bonus value of the loyalty program for current operation if available. |
| loyalty-program | The name of the loyalty program for current operation if available. |
| descriptor | Bank identifier of the payment recipient. |
| original-gate-descriptor | Descriptor, which is set on gate level in the system. |
| error-message | If status in declined, error, filtered this parameter contains the reason for decline. |
| error-code | The error code is case status in declined, error, filtered. |
| by-request-sn | Serial number assigned to the specific request by gate.payneteasy.eu. If this field exist in status request, status response return for this specific request. |
| verified-3d-status | See [3D Secure Status List](https://doc.payneteasy.com/integration/reference/statuses.html.md) for details. |
| verified-rsc-status | Returned if Random Sum Check was performed. See [Alternative cardholder authentication](https://doc.payneteasy.com/integration/reference/3ds_overview.html.md) |
| eci | Electronic Commerce Indicator (Visa). |
| ips-src-payment-product-code | Code for card set by multinational financial service (Visa/Mastercard). |
| ips-src-payment-product-name | Decrypted code for card set by multinational financial service (Visa/Mastercard). |
| ips-src-payment-type-code | Type of card code set by multinational financial service (Visa/Mastercard). |
| ips-src-payment-type-name | Decrypted code for type of card set by multinational financial service (Visa/Mastercard). |
| merchantdata | If provided in initial request, merchant_data parameter and its value will be included in status response. |
| initial-amount | Amount, set in initiating transaction, without any fees or commissions. This value can’t change during the transaction flow. |
| seller-commission | Total commission for processed transaction. This is optional parameter. Please contact your manager in Payneteasy, if you would like to receive it. |
| acquirer-commission | Acquirer commission for processed transaction. This is optional parameter. Please contact your manager in Payneteasy, if you would like to receive it. |
| motivational-message | This is an optional message which contains extended information about the reason for the declined transaction. |
| transaction-date | Date of final status assignment for transaction. |
| orig-amount | Contains the original request amount if it was converted on auxiliary endpoint in Parallel form integration. Relevant only for Payment Cashier transactions. |
| orig-currency | Contains the original request currency if it was converted on auxiliary endpoint in Parallel form integration. Relevant only for Payment Cashier transactions. |
#### Pa Req Form Status Response Parameters
| Name | Description |
|------------------------|-----------------------------------------------------------------|
| tds-pareq-form-pareq | ACS 3DS Pa Req data, which received by the Connecting Party. |
| tds-pareq-form-acs-url | ACS URL to redirect the Payer to 3DS 1.0.2 Authentication Flow. |
#### CReq Form Status Response Parameters
| Name | Description |
|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| tds-creq-form-creq | A CReq message initiates Cardholder interaction in a Challenge Flow and is used to carry authentication data from the Cardholder. It is formed by the 3DS Server and is posted through the Cardholder’s browser by Connecting Party to the ACS URL. |
| tds-creq-form-acs-url | ACS URL to redirect the Payer for Challenge Flow. |
#### Method Url Frame Status Response Parameters
| Name | Description |
|------------------------------------------|--------------------------------------------------------------------------------------------------------|
| tds-method-url-frame-3ds-server-trans-id | Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction. |
| tds-method-url-frame-3ds-method-url | 3DS Method URL used in iframe form which is provided to Payer browser by Connecting Party. |
Rules to form the HTML form.
threeDSMethod Data (threeDSMethod NotificationURL + threeDSServer TransID).
#### Request Example
```http
POST /paynet/api/v4/status/46750 HTTP/1.1
User-Agent: curl/7.88.1
Accept: */*
Authorization: OAuth oauth_consumer_key="Test_Merchant", oauth_nonce="BKOz6eHOs6sDJlLPAJhbDHAaXCy9xxNv", oauth_signature="eQXkV%2BJdiqJlyRqNaEzIKmYa3FZzUjdcMR6lXSfRn9tOYKUNPxI3UKU%2F%2FGsPpofXL%2B2RBjGh3Gqv%2BZBoKaVKOgNKwNNwpA4IOaskV71uuMbZCp0gPEbS%2BVaWLD8vzqpcgZ%2Bd5DRNMfimyXkWVWbsMUYj8N%2BSpXl4YnGIo0nXz9Q0Ppxetie3EG9NrN7CNu7NdovVjmstfYqpDRv9OhLo4tSQTD9C6bWvW2kmEvZsb2d1KANsGUW6rXyjkIoPxJ2XigIXBOUfwSWj9cV7SsZ%2FNk%2FVjNWgav2uw9J9I%2FiTqLLcKZ1pTWj1WOMwXhfoMCP10XOAOe72CQHX0DJL%2BFt01jmOXLvLdEkUZTFzsC6DGfHSDdcsjXquc9gxFKVr3d8e15by3566UI4pXKef%2Fe%2B3Ytvlrj7IUhIcNyA%2BVXp%2FwivxgwYu2xpQJMs6wlvw6Lz3N2wcFRqLs5ZEbdZ1%2F29pox8XW0ae8yZ2z2PClPzmJIoDcOr0GEtwyz5ByyeW0m33XA67UbPN6rwbdlVL2gwMqWwkn7KDYp7%2BifP%2B2BdbyXnw2LeJcuYDYAIDHa%2Bi0P09ZVToBpeLOx%2FobSF2y%2FsheVgo0O%2FRWtUEEXONvd0n7hEdnJ7mMYNivNitbfQ4SryQ2o8CdUDk9RgEaR7pn7ybTi4rQEhDqWF8sFMtaKhFn9o%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1734327207", oauth_version="1.0"
Content-Length: 58
Content-Type: application/x-www-form-urlencoded
Connection: close
client_orderid=1&login=Test_Merchant&order_id=7364742
```
#### Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Mon, 16 Dec 2024 05:38:33 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 1469
type=status-response
&serial-number=00000000-0000-0000-0000-000002f38234
&merchant-order-id=123456
&processor-tx-id=PNTEST-7364748
&paynet-order-id=7364748
&status=approved
&amount=10.42
¤cy=USD
&descriptor=Test
&original-gate-descriptor=Test
&transaction-type=transfer
&receipt-id=2f885ae0-5220-3549-8eb5-622f4201f882
&name=John+Doe
&cardholder-name=John+Doe
&card-exp-month=12
&card-exp-year=2099
&processor-rrn=0435171505391
&approval-code=466875
&order-stage=transfer_approved
&last-four-digits=5721
&bin=421070
&card-type=VISA
&bank-name=DEMIRBANK+OJSC
&dest-bank-name=JPMORGAN+CHASE+BANK+N.A.
&dest-bin=423261
&dest-last-four-digits=1636
&dest-card-type=VISA
&auth-response-code=00
&paynet-processing-date=2024-12-16+08%3A37%3A25+MSK
&acquirer-processing-date=2024-12-16+08%3A37%3A25+MSK
&processor-auth-credit-code=311830
&card-hash-id=2511341
&destination-card-hash-id=2511340
&card-country-alpha-three-code=AZE
&destination-card-country-alpha-three-code=USA
&verified-3d-status=NOT_AUTHENTICATED
&processor-credit-rrn=0435147814453
&processor-credit-arn=899834666
&processor-debit-arn=668539305
&ips-src-payment-product-code=UNK
&ips-src-payment-product-name=Unknown
&ips-src-payment-type-code=Credit
&ips-src-payment-type-name=VISA+Credit
&ips-dst-payment-product-code=UNK
&ips-dst-payment-product-name=Unknown
&ips-dst-payment-type-code=Prepaid
&ips-dst-payment-type-name=VISA+Prepaid
&initial-amount=10.42
&transaction-date=2024-12-16+08%3A37%3A34+MSK
```
#### Fail Response Example
```http
HTTP/1.1 200
Server: server
Date: Mon, 16 Dec 2024 05:33:57 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 164
type=status-response
&serial-number=00000000-0000-0000-0000-000002f38231
&merchant-order-id=1
&status=error
&error-message=AMBIGUOUS_CLIENT_ORDER_ID
&error-code=124
```
#### Open API Collection
Open this method in the OpenAPI Reference
View in OpenAPI
### /api/v4/transfer-form
#### Introduction
Transfer is a type of complex transaction that allows to move funds between bank cards (Primary Account Number - PAN), card tokens (Recurring Payment ID - RPI) and Connecting Party bank account (deposits).
Transfer Form integration is relevant for Connecting Party who are not able to accept Connecting Party order ID. card details (Connecting Party’s website must complete PCI DSS certification). Using Transfer Form integration Connecting Party is released of accepting payment details. In this case the accepting and processing of payment details is carried out on the Payneteasy side (if PAN is not sent). This type of integration also allows the Sender (for transfers between cards) or Receiver (for deposit to card) to submit their PAN on Payneteasy side.
Transfer is initiated through HTTPS POST request to the [URL](#transfer-form-api-urls) with the [required parameters](#api-v4-transfer-form-request-parameters-usage) depending on a certain transfer Use-Case (see below). Use [RSA-SHA256](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md) for authentication.
Transfer Form Use-Cases diagram:
```plantuml
hide members
hide circle
circle " " as c2
package From <> {
class "Form" as f1a
class "Card number\n(Pan)" as pan1a
class "Reccuring Payment ID\n(RPI)" as rpi1a
class "Connecting Party Account\n(Deposit to card)" as dca
}
package To <> {
class "Card number\n(Pan)" as pan2
class "Reccuring Payment ID\n(RPI)" as rpi2
class "Form" as f2
}
f1a --|> pan2
f1a --|> rpi2
f1a -- c2
pan1a -- c2
rpi1a -- c2
dca -- c2
dca -[hidden]> f2
c2 --|> f2
```
| Form to PAN | Transfer from Form to PAN occurs when transferring funds from payment details indicated in form to bank card for which its number is indicated. |
|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Form to RPI | Transfer from Form to RPI occurs when funds are transferred from payment details indicated in form to bank card for which its recurring payment id is indicated. |
| PAN to Form | Transfer from RPI to Form occurs when funds are transferred from one bank card for which its number is indicated to payment details indicated in form. |
| RPI to Form | Transfer from RPI to Form occurs when funds are transferred from one bank card for which its recurring payment id is indicated to payment details indicated in form. |
| Form to Form | Transfer from Form to Form occurs when funds are transferred from payment details indicated in form to another payment details indicated in form. |
| Deposit to Form | Transfer from deposit to Form occurs when funds are transferred from Connecting Party account to payment details indicated in form. |
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|---------------------------------------------------------------------------------|------------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v4/transfer-form/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v4/transfer-form/ENDPOINTID |
| https://sandbox.payneteasy.eu/paynet/api/v4/transfer-form/group/ENDPOINTGROUPID | https://gate.payneteasy.eu/paynet/api/v4/transfer-form/group/ENDPOINTGROUPID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded and [Authorization headers](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md).
Form to PAN
| Parameter | Description | Value |
|-------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| destination-card-no, alias destination | Receiver\`s card PAN. | `Necessity`: Required `Type`: Numeric `Length`: 19 |
| deposit2card | Marker of deposit to card transfer. If true, no sender cardholder data is needed to process the transaction. If false, sender cardholder data is needed. | `Value`: False `Type`: Boolean |
| ipaddress | The Sender or Receiver’s IP address, include for fraud screening purposes. NB: 45 is for IPv4 tunneling like 0000:0000:0000:0000:0000:0000:192.168.100.101. | `Necessity`: Required `Type`: String `Length`: 45 |
| amount | Amount to be transferred. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. | `Necessity`: Required `Type`: Numeric `Length`: 10 |
| currency | Currency the transaction is charged in (three-letter currency code). Example of valid parameter values are: USD for US Dollar, EUR for European Euro. | `Necessity`: Required `Type`: String `Length`: 3 |
| order_desc | Order description. | `Necessity`: Required `Type`: String `Length`: 64k |
| client_orderid | Connecting Party order ID. | `Necessity`: Required `Type`: String `Length`: 128 |
| first_name | Sender or Receiver’s first name. | `Necessity`: Optional `Type`: String `Length`: 50 |
| last_name | Sender or Receiver’s last name. | `Necessity`: Optional `Type`: String `Length`: 50 |
| ssn | Last four digits of the Sender or Receivers’s social security number. | `Necessity`: Optional `Type`: Numeric `Length`: 4 |
| birthday | Sender or Receiver’s birthday. | `Necessity`: Optional `Type`: Numeric `Length`: 8 |
| address1 | Sender or Receiver’s address. (Please note that in some cases it is not possible to send address length more than 50 characters. Please contact your manager for more details.) | `Necessity`: Optional `Type`: String `Length`: 256 |
| city | Sender or Receiver’s city. | `Necessity`: Optional `Type`: String `Length`: 50 |
| state | Sender or Receiver’s state (two-letter state code). Please see Mandatory State Codes for a list of valid state codes. Required for USA, Canada and Australia. | `Necessity`: Optional `Type`: String `Length`: 2 |
| zip_code | Sender or Receiver\`s zip code. | `Necessity`: Optional `Type`: String `Length`: 10 |
| country | Sender or Receiver’s country (two letter abbreviation). | `Necessity`: Optional `Type`: String `Length`: 2 |
| phone | Sender or Receiver’s full international phone number, including country suffix. | `Necessity`: Optional `Type`: String `Length`: 15 |
| cell_phone | Sender or Receiver’s full international cell phone number, including country suffix. | `Necessity`: Optional `Type`: String `Length`: 15 |
| purpose | Destination to where the payment goes. It is useful for the merchants who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account. Sample values are: +9999999999;mail@example.com etc. This value will be used by fraud monitoring system | `Necessity`: Optional `Type`: String `Length`: 128 |
| email | Sender or Receiver’s email address. | `Necessity`: Optional `Type`: String `Length`: 50 |
| site_url | URL the original transfer is made from. | `Necessity`: Optional `Type`: String `Length`: 128 |
| redirect_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved or declined. Optional for direct integration (non-form) deposit2card. This parameter must be used if there is neither redirect_success_url nor redirect_fail_url. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| redirect_success_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is approved. This parameter should not be used to retrieve results from Payneteasy gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to the backend server_callback_url must be used instead. gate.payneteasy.eu should be passed if non-3DS schema for transactions processing is used and there is no need to redirect Sender or Receiver anywhere. This parameter must be used if there is no redirect_url. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| redirect_fail_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is declined or filtered. This parameter should not be used to retrieve results from Payneteasy gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to the backend server_callback_url must be used instead. gate.payneteasy.eu should be passed if non-3DS schema for transactions processing is used and there is no need to redirect Sender or Receiver anywhere. This parameter must be used if there is no redirect_url. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| preferred_language | Sender or Receiver’s two-letter language code for multi-language transfer forms. | `Necessity`: Optional `Type`: String `Length`: 2 |
| merchant_form_data | Parameters sent in merchant_form_data API parameter are parsed into macros with the same name, the parameter is url-encoded, example testparam%3Dtest1%26mynewparam%3Dtest2 and is parsed into $MFD_testparam = test1 and $MFD_mynewparam = test2 macros in the form. Parameter name characters [a-zA-Z0-9], parameter value characters [a-zA-Z0-9], only characters = and & are allowed as control characters, 2MB max size. For example, this parameter can be used to display payment form in light/dark mode depending on the value passed by Connecting Party (e.g. pass merchant_form_data=theme%3Ddark in request and $MFD_theme macro placeholder on payment form will be changed to dark. | `Necessity`: Optional `Type`: String `Length`: 128 |
| server_callback_url | URL, where the transaction status is sent to. Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to server_callback_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of notify_url. If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). | `Necessity`: Optional `Type`: String `Length`: 1024 |
| notify_url | URL, where the transaction status is sent to. Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to notify_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of server_callback_url. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. | `Necessity`: Optional `Type`: String `Length`: 1024 |
Form to RPI
| Parameter | Description | Value |
|---------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| destination_card_recurring_payment_id | Receiver\`s recurring payment ID. To create destination_card_recurring_payment_id please see Card Reference ID Creation. | `Necessity`: Required `Type`: Long |
| deposit2card | Marker of deposit to card transfer. If true, no sender cardholder data is needed to process the transaction. If false, sender cardholder data is needed. | `Value`: False `Type`: Boolean |
| ipaddress | The Sender or Receiver’s IP address, include for fraud screening purposes. NB: 45 is for IPv4 tunneling like 0000:0000:0000:0000:0000:0000:192.168.100.101. | `Necessity`: Required `Type`: String `Length`: 45 |
| amount | Amount to be transferred. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. | `Necessity`: Required `Type`: Numeric `Length`: 10 |
| currency | Currency the transaction is charged in (three-letter currency code). Example of valid parameter values are: USD for US Dollar, EUR for European Euro. | `Necessity`: Required `Type`: String `Length`: 3 |
| order_desc | Order description. | `Necessity`: Required `Type`: String `Length`: 64k |
| client_orderid | Connecting Party order ID. | `Necessity`: Required `Type`: String `Length`: 128 |
| first_name | Sender or Receiver’s first name. | `Necessity`: Optional `Type`: String `Length`: 50 |
| last_name | Sender or Receiver’s last name. | `Necessity`: Optional `Type`: String `Length`: 50 |
| ssn | Last four digits of the Sender or Receivers’s social security number. | `Necessity`: Optional `Type`: Numeric `Length`: 4 |
| birthday | Sender or Receiver’s birthday. | `Necessity`: Optional `Type`: Numeric `Length`: 8 |
| address1 | Sender or Receiver’s address. (Please note that in some cases it is not possible to send address length more than 50 characters. Please contact your manager for more details.) | `Necessity`: Optional `Type`: String `Length`: 256 |
| city | Sender or Receiver’s city. | `Necessity`: Optional `Type`: String `Length`: 50 |
| state | Sender or Receiver’s state (two-letter state code). Please see Mandatory State Codes for a list of valid state codes. Required for USA, Canada and Australia. | `Necessity`: Optional `Type`: String `Length`: 2 |
| zip_code | Sender or Receiver\`s zip code. | `Necessity`: Optional `Type`: String `Length`: 10 |
| country | Sender or Receiver’s country (two letter abbreviation). | `Necessity`: Optional `Type`: String `Length`: 2 |
| phone | Sender or Receiver’s full international phone number, including country suffix. | `Necessity`: Optional `Type`: String `Length`: 15 |
| cell_phone | Sender or Receiver’s full international cell phone number, including country suffix. | `Necessity`: Optional `Type`: String `Length`: 15 |
| purpose | Destination to where the payment goes. It is useful for the merchants who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account. Sample values are: +9999999999;mail@example.com etc. This value will be used by fraud monitoring system | `Necessity`: Optional `Type`: String `Length`: 128 |
| email | Sender or Receiver’s email address. | `Necessity`: Optional `Type`: String `Length`: 50 |
| site_url | URL the original transfer is made from. | `Necessity`: Optional `Type`: String `Length`: 128 |
| redirect_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved or declined. Optional for direct integration (non-form) deposit2card. This parameter must be used if there is neither redirect_success_url nor redirect_fail_url. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| redirect_success_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is approved. This parameter should not be used to retrieve results from Payneteasy gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to the backend server_callback_url must be used instead. gate.payneteasy.eu should be passed if non-3DS schema for transactions processing is used and there is no need to redirect Sender or Receiver anywhere. This parameter must be used if there is no redirect_url. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| redirect_fail_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is declined or filtered. This parameter should not be used to retrieve results from Payneteasy gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to the backend server_callback_url must be used instead. gate.payneteasy.eu should be passed if non-3DS schema for transactions processing is used and there is no need to redirect Sender or Receiver anywhere. This parameter must be used if there is no redirect_url. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| preferred_language | Sender or Receiver’s two-letter language code for multi-language transfer forms. | `Necessity`: Optional `Type`: String `Length`: 2 |
| merchant_form_data | Parameters sent in merchant_form_data API parameter are parsed into macros with the same name, the parameter is url-encoded, example testparam%3Dtest1%26mynewparam%3Dtest2 and is parsed into $MFD_testparam = test1 and $MFD_mynewparam = test2 macros in the form. Parameter name characters [a-zA-Z0-9], parameter value characters [a-zA-Z0-9], control characters [=&], 2MB max size. For example, this parameter can be used to display payment form in light/dark mode depending on the value passed by Connecting Party (e.g. pass merchant_form_data=theme%3Ddark in request and $MFD_theme macro placeholder on payment form will be changed to dark. | `Necessity`: Optional `Type`: String `Length`: 128 |
| server_callback_url | URL, where the transaction status is sent to. Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to server_callback_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of notify_url. If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). | `Necessity`: Optional `Type`: String `Length`: 1024 |
| notify_url | URL, where the transaction status is sent to. Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to notify_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of server_callback_url. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. | `Necessity`: Optional `Type`: String `Length`: 1024 |
PAN to Form
| Parameter | Description | Value |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| credit_card_number | Sender\`s credit card number. | `Necessity`: Required `Type`: Numeric `Length`: 19 |
| cvv2 | Sender\`s CVV2 code. CVV2 (Card verification value) is the three of four digit number farthest to the right on the flip side of a credit card. | `Necessity`: Required `Type`: String `Length`: 3-4 |
| expire_month | Sender credit card’s month of expiration. | `Necessity`: Required `Type`: String `Length`: 2 |
| expire_year | Sender credit card’s year of expiration. | `Necessity`: Required `Type`: String `Length`: 2-4 |
| card_printed_name | Sender\`s card printed name. | `Necessity`: Required `Type`: String `Length`: 128 |
| deposit2card | Marker of deposit to card transfer. If true, no sender cardholder data is needed to process the transaction. If false, sender cardholder data is needed. | `Value`: False `Type`: Boolean |
| ipaddress | The Sender or Receiver’s IP address, include for fraud screening purposes. NB: 45 is for IPv4 tunneling like 0000:0000:0000:0000:0000:0000:192.168.100.101. | `Necessity`: Required `Type`: String `Length`: 45 |
| amount | Amount to be transferred. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. | `Necessity`: Required `Type`: Numeric `Length`: 10 |
| currency | Currency the transaction is charged in (three-letter currency code). Example of valid parameter values are: USD for US Dollar, EUR for European Euro. | `Necessity`: Required `Type`: String `Length`: 3 |
| order_desc | Order description. | `Necessity`: Required `Type`: String `Length`: 64k |
| client_orderid | Connecting Party order ID. | `Necessity`: Required `Type`: String `Length`: 128 |
| first_name | Sender or Receiver’s first name. | `Necessity`: Optional `Type`: String `Length`: 50 |
| last_name | Sender or Receiver’s last name. | `Necessity`: Optional `Type`: String `Length`: 50 |
| ssn | Last four digits of the Sender or Receivers’s social security number. | `Necessity`: Optional `Type`: Numeric `Length`: 4 |
| birthday | Sender or Receiver’s birthday. | `Necessity`: Optional `Type`: Numeric `Length`: 8 |
| address1 | Sender or Receiver’s address. (Please note that in some cases it is not possible to send address length more than 50 characters. Please contact your manager for more details.) | `Necessity`: Optional `Type`: String `Length`: 256 |
| city | Sender or Receiver’s city. | `Necessity`: Optional `Type`: String `Length`: 50 |
| state | Sender or Receiver’s state (two-letter state code). Please see Mandatory State Codes for a list of valid state codes. Required for USA, Canada and Australia. | `Necessity`: Optional `Type`: String `Length`: 2 |
| zip_code | Sender or Receiver\`s zip code. | `Necessity`: Optional `Type`: String `Length`: 10 |
| country | Sender or Receiver’s country (two letter abbreviation). | `Necessity`: Optional `Type`: String `Length`: 2 |
| phone | Sender or Receiver’s full international phone number, including country suffix. | `Necessity`: Optional `Type`: String `Length`: 15 |
| cell_phone | Sender or Receiver’s full international cell phone number, including country suffix. | `Necessity`: Optional `Type`: String `Length`: 15 |
| purpose | Destination to where the payment goes. It is useful for the merchants who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account. Sample values are: +9999999999;mail@example.com etc. This value will be used by fraud monitoring system | `Necessity`: Optional `Type`: String `Length`: 128 |
| email | Sender or Receiver’s email address. | `Necessity`: Optional `Type`: String `Length`: 50 |
| site_url | URL the original transfer is made from. | `Necessity`: Optional `Type`: String `Length`: 128 |
| redirect_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved or declined. Optional for direct integration (non-form) deposit2card. This parameter must be used if there is neither redirect_success_url nor redirect_fail_url. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| redirect_success_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is approved. This parameter should not be used to retrieve results from Payneteasy gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to the backend server_callback_url must be used instead. gate.payneteasy.eu should be passed if non-3DS schema for transactions processing is used and there is no need to redirect Sender or Receiver anywhere. This parameter must be used if there is no redirect_url. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| redirect_fail_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is declined or filtered. This parameter should not be used to retrieve results from Payneteasy gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to the backend server_callback_url must be used instead. gate.payneteasy.eu should be passed if non-3DS schema for transactions processing is used and there is no need to redirect Sender or Receiver anywhere. This parameter must be used if there is no redirect_url. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| preferred_language | Sender or Receiver’s two-letter language code for multi-language transfer forms. | `Necessity`: Optional `Type`: String `Length`: 2 |
| merchant_form_data | Parameters sent in merchant_form_data API parameter are parsed into macros with the same name, the parameter is url-encoded, example testparam%3Dtest1%26mynewparam%3Dtest2 and is parsed into $MFD_testparam = test1 and $MFD_mynewparam = test2 macros in the form. Parameter name characters [a-zA-Z0-9], parameter value characters [a-zA-Z0-9], control characters [=&], 2MB max size. For example, this parameter can be used to display payment form in light/dark mode depending on the value passed by Connecting Party (e.g. pass merchant_form_data=theme%3Ddark in request and $MFD_theme macro placeholder on payment form will be changed to dark. | `Necessity`: Optional `Type`: String `Length`: 128 |
| server_callback_url | URL, where the transaction status is sent to. Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to server_callback_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of notify_url. If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). | `Necessity`: Optional `Type`: String `Length`: 1024 |
| notify_url | URL, where the transaction status is sent to. Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to notify_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of server_callback_url. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. | `Necessity`: Optional `Type`: String `Length`: 1024 |
RPI to Form
| Parameter | Description | Value |
|---------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| cvv2 | Sender\`s CVV2 code. CVV2 (Card verification value) is the three of four digit number farthest to the right on the flip side of a credit card. | `Necessity`: Required `Type`: String `Length`: 3-4 |
| card_recurring_payment_id | Sender\`s recurring payment ID. To create card_recurring_payment_id please see Card Reference ID Creation. | `Necessity`: Required `Type`: Long |
| deposit2card | Marker of deposit to card transfer. If true, no sender cardholder data is needed to process the transaction. If false, sender cardholder data is needed. | `Value`: False `Type`: Boolean |
| ipaddress | The Sender or Receiver’s IP address, include for fraud screening purposes. NB: 45 is for IPv4 tunneling like 0000:0000:0000:0000:0000:0000:192.168.100.101. | `Necessity`: Required `Type`: String `Length`: 45 |
| amount | Amount to be transferred. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. | `Necessity`: Required `Type`: Numeric `Length`: 10 |
| currency | Currency the transaction is charged in (three-letter currency code). Example of valid parameter values are: USD for US Dollar, EUR for European Euro. | `Necessity`: Required `Type`: String `Length`: 3 |
| order_desc | Order description. | `Necessity`: Required `Type`: String `Length`: 64k |
| client_orderid | Connecting Party order ID. | `Necessity`: Required `Type`: String `Length`: 128 |
| first_name | Sender or Receiver’s first name. | `Necessity`: Optional `Type`: String `Length`: 50 |
| last_name | Sender or Receiver’s last name. | `Necessity`: Optional `Type`: String `Length`: 50 |
| ssn | Last four digits of the Sender or Receivers’s social security number. | `Necessity`: Optional `Type`: Numeric `Length`: 4 |
| birthday | Sender or Receiver’s birthday. | `Necessity`: Optional `Type`: Numeric `Length`: 8 |
| address1 | Sender or Receiver’s address. (Please note that in some cases it is not possible to send address length more than 50 characters. Please contact your manager for more details.) | `Necessity`: Optional `Type`: String `Length`: 256 |
| city | Sender or Receiver’s city. | `Necessity`: Optional `Type`: String `Length`: 50 |
| state | Sender or Receiver’s state (two-letter state code). Please see Mandatory State Codes for a list of valid state codes. Required for USA, Canada and Australia. | `Necessity`: Optional `Type`: String `Length`: 2 |
| zip_code | Sender or Receiver\`s zip code. | `Necessity`: Optional `Type`: String `Length`: 10 |
| country | Sender or Receiver’s country (two letter abbreviation). | `Necessity`: Optional `Type`: String `Length`: 2 |
| phone | Sender or Receiver’s full international phone number, including country suffix. | `Necessity`: Optional `Type`: String `Length`: 15 |
| cell_phone | Sender or Receiver’s full international cell phone number, including country suffix. | `Necessity`: Optional `Type`: String `Length`: 15 |
| purpose | Destination to where the payment goes. It is useful for the merchants who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account. Sample values are: +9999999999;mail@example.com etc. This value will be used by fraud monitoring system | `Necessity`: Optional `Type`: String `Length`: 128 |
| email | Sender or Receiver’s email address. | `Necessity`: Optional `Type`: String `Length`: 50 |
| site_url | URL the original transfer is made from. | `Necessity`: Optional `Type`: String `Length`: 128 |
| redirect_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved or declined. Optional for direct integration (non-form) deposit2card. This parameter must be used if there is neither redirect_success_url nor redirect_fail_url. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| redirect_success_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is approved. This parameter should not be used to retrieve results from Payneteasy gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to the backend server_callback_url must be used instead. gate.payneteasy.eu should be passed if non-3DS schema for transactions processing is used and there is no need to redirect Sender or Receiver anywhere. This parameter must be used if there is no redirect_url. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| redirect_fail_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is declined or filtered. This parameter should not be used to retrieve results from Payneteasy gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to the backend server_callback_url must be used instead. gate.payneteasy.eu should be passed if non-3DS schema for transactions processing is used and there is no need to redirect Sender or Receiver anywhere. This parameter must be used if there is no redirect_url. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| preferred_language | Sender or Receiver’s two-letter language code for multi-language transfer forms. | `Necessity`: Optional `Type`: String `Length`: 2 |
| merchant_form_data | Parameters sent in merchant_form_data API parameter are parsed into macros with the same name, the parameter is url-encoded, example testparam%3Dtest1%26mynewparam%3Dtest2 and is parsed into $MFD_testparam = test1 and $MFD_mynewparam = test2 macros in the form. Parameter name characters [a-zA-Z0-9], parameter value characters [a-zA-Z0-9], control characters [=&], 2MB max size. For example, this parameter can be used to display payment form in light/dark mode depending on the value passed by Connecting Party (e.g. pass merchant_form_data=theme%3Ddark in request and $MFD_theme macro placeholder on payment form will be changed to dark. | `Necessity`: Optional `Type`: String `Length`: 128 |
| server_callback_url | URL, where the transaction status is sent to. Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to server_callback_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of notify_url. If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). | `Necessity`: Optional `Type`: String `Length`: 1024 |
| notify_url | URL, where the transaction status is sent to. Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to notify_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of server_callback_url. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. | `Necessity`: Optional `Type`: String `Length`: 1024 |
Form to Form
| Parameter | Description | Value |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| deposit2card | Marker of deposit to card transfer. If true, no sender cardholder data is needed to process the transaction. If false, sender cardholder data is needed. | `Value`: False `Type`: Boolean |
| ipaddress | The Sender or Receiver’s IP address, include for fraud screening purposes. NB: 45 is for IPv4 tunneling like 0000:0000:0000:0000:0000:0000:192.168.100.101. | `Necessity`: Required `Type`: String `Length`: 45 |
| amount | Amount to be transferred. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. | `Necessity`: Required `Type`: Numeric `Length`: 10 |
| currency | Currency the transaction is charged in (three-letter currency code). Example of valid parameter values are: USD for US Dollar, EUR for European Euro. | `Necessity`: Required `Type`: String `Length`: 3 |
| order_desc | Order description. | `Necessity`: Required `Type`: String `Length`: 64k |
| client_orderid | Connecting Party order ID. | `Necessity`: Required `Type`: String `Length`: 128 |
| first_name | Sender or Receiver’s first name. | `Necessity`: Optional `Type`: String `Length`: 50 |
| last_name | Sender or Receiver’s last name. | `Necessity`: Optional `Type`: String `Length`: 50 |
| ssn | Last four digits of the Sender or Receiver’s social security number. | `Necessity`: Optional `Type`: Numeric `Length`: 4 |
| birthday | Sender or Receiver’s birthday. | `Necessity`: Optional `Type`: Numeric `Length`: 8 |
| address1 | Sender or Receiver’s address. (Please note that in some cases it is not possible to send address length more than 50 characters. Please contact your manager for more details.) | `Necessity`: Optional `Type`: String `Length`: 256 |
| city | Sender or Receiver’s city. | `Necessity`: Optional `Type`: String `Length`: 50 |
| state | Sender or Receiver’s state (two-letter state code). Please see Mandatory State Codes for a list of valid state codes. Required for USA, Canada and Australia. | `Necessity`: Optional `Type`: String `Length`: 2 |
| zip_code | Sender or Receiver\`s zip code. | `Necessity`: Optional `Type`: String `Length`: 10 |
| country | Sender or Receiver’s country (two letter abbreviation). | `Necessity`: Optional `Type`: String `Length`: 2 |
| phone | Sender or Receiver’s full international phone number, including country suffix. | `Necessity`: Optional `Type`: String `Length`: 15 |
| cell_phone | Sender or Receiver’s full international cell phone number, including country suffix. | `Necessity`: Optional `Type`: String `Length`: 15 |
| purpose | Destination to where the payment goes. It is useful for the merchants who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account. Sample values are: +9999999999;mail@example.com etc. This value will be used by fraud monitoring system | `Necessity`: Optional `Type`: String `Length`: 128 |
| email | Sender or Receiver’s email address. | `Necessity`: Optional `Type`: String `Length`: 50 |
| site_url | URL the original transfer is made from. | `Necessity`: Optional `Type`: String `Length`: 128 |
| redirect_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved or declined. Optional for direct integration (non-form) deposit2card. This parameter must be used if there is neither redirect_success_url nor redirect_fail_url. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| redirect_success_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is approved. This parameter should not be used to retrieve results from Payneteasy gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to the backend server_callback_url must be used instead. gate.payneteasy.eu should be passed if non-3DS schema for transactions processing is used and there is no need to redirect Sender or Receiver anywhere. This parameter must be used if there is no redirect_url. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| redirect_fail_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is declined or filtered. This parameter should not be used to retrieve results from Payneteasy gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to the backend server_callback_url must be used instead. gate.payneteasy.eu should be passed if non-3DS schema for transactions processing is used and there is no need to redirect Sender or Receiver anywhere. This parameter must be used if there is no redirect_url. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| preferred_language | Sender or Receiver’s two-letter language code for multi-language transfer forms. | `Necessity`: Optional `Type`: String `Length`: 2 |
| merchant_form_data | Parameters sent in merchant_form_data API parameter are parsed into macros with the same name, the parameter is url-encoded, example testparam%3Dtest1%26mynewparam%3Dtest2 and is parsed into $MFD_testparam = test1 and $MFD_mynewparam = test2 macros in the form. Parameter name characters [a-zA-Z0-9], parameter value characters [a-zA-Z0-9], control characters [=&], 2MB max size. For example, this parameter can be used to display payment form in light/dark mode depending on the value passed by Connecting Party (e.g. pass merchant_form_data=theme%3Ddark in request and $MFD_theme macro placeholder on payment form will be changed to dark. | `Necessity`: Optional `Type`: String `Length`: 128 |
| server_callback_url | URL, where the transaction status is sent to. Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to server_callback_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of notify_url. If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). | `Necessity`: Optional `Type`: String `Length`: 1024 |
| notify_url | URL, where the transaction status is sent to. Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to notify_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of server_callback_url. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. | `Necessity`: Optional `Type`: String `Length`: 1024 |
Deposit to Form
| Parameter | Description | Value |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| deposit2card | Marker of deposit to card transfer. If true, no sender cardholder data is needed to process the transaction. If false, sender cardholder data is needed. | `Value`: True `Type`: Boolean |
| ipaddress | The Sender or Receiver’s IP address, include for fraud screening purposes. NB: 45 is for IPv4 tunneling like 0000:0000:0000:0000:0000:0000:192.168.100.101. | `Necessity`: Required `Type`: String `Length`: 45 |
| amount | Amount to be transferred. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. | `Necessity`: Required `Type`: Numeric `Length`: 10 |
| currency | Currency the transaction is charged in (three-letter currency code). Example of valid parameter values are: USD for US Dollar, EUR for European Euro. | `Necessity`: Required `Type`: String `Length`: 3 |
| order_desc | Order description. | `Necessity`: Required `Type`: String `Length`: 64k |
| client_orderid | Connecting Party order ID. | `Necessity`: Required `Type`: String `Length`: 128 |
| first_name | Sender or Receiver’s first name. | `Necessity`: Optional `Type`: String `Length`: 50 |
| last_name | Sender or Receiver’s last name. | `Necessity`: Optional `Type`: String `Length`: 50 |
| ssn | Last four digits of the Sender or Receiver’s social security number. | `Necessity`: Optional `Type`: Numeric `Length`: 4 |
| birthday | Sender or Receiver’s birthday. | `Necessity`: Optional `Type`: Numeric `Length`: 8 |
| address1 | Sender or Receiver’s address. (Please note that in some cases it is not possible to send address length more than 50 characters. Please contact your manager for more details.) | `Necessity`: Optional `Type`: String `Length`: 256 |
| city | Sender or Receiver’s city. | `Necessity`: Optional `Type`: String `Length`: 50 |
| state | Sender or Receiver’s state (two-letter state code). Please see Mandatory State Codes for a list of valid state codes. Required for USA, Canada and Australia. | `Necessity`: Optional `Type`: String `Length`: 2 |
| zip_code | Sender or Receiver\`s zip code. | `Necessity`: Optional `Type`: String `Length`: 10 |
| country | Sender or Receiver’s country (two letter abbreviation). | `Necessity`: Optional `Type`: String `Length`: 2 |
| phone | Sender or Receiver’s full international phone number, including country suffix. | `Necessity`: Optional `Type`: String `Length`: 15 |
| cell_phone | Sender or Receiver’s full international cell phone number, including country suffix. | `Necessity`: Optional `Type`: String `Length`: 15 |
| purpose | Destination to where the payment goes. It is useful for the merchants who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account. Sample values are: +9999999999;mail@example.com etc. This value will be used by fraud monitoring system | `Necessity`: Optional `Type`: String `Length`: 128 |
| email | Sender or Receiver’s email address. | `Necessity`: Optional `Type`: String `Length`: 50 |
| site_url | URL the original transfer is made from. | `Necessity`: Optional `Type`: String `Length`: 128 |
| redirect_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved or declined. Optional for direct integration (non-form) deposit2card. This parameter must be used if there is neither redirect_success_url nor redirect_fail_url. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| redirect_success_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is approved. This parameter should not be used to retrieve results from Payneteasy gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to the backend server_callback_url must be used instead. gate.payneteasy.eu should be passed if non-3DS schema for transactions processing is used and there is no need to redirect Sender or Receiver anywhere. This parameter must be used if there is no redirect_url. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| redirect_fail_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is declined or filtered. This parameter should not be used to retrieve results from Payneteasy gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to the backend server_callback_url must be used instead. gate.payneteasy.eu should be passed if non-3DS schema for transactions processing is used and there is no need to redirect Sender or Receiver anywhere. This parameter must be used if there is no redirect_url. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| preferred_language | Sender or Receiver’s two-letter language code for multi-language transfer forms. | `Necessity`: Optional `Type`: String `Length`: 2 |
| merchant_form_data | Parameters sent in merchant_form_data API parameter are parsed into macros with the same name, the parameter is url-encoded, example testparam%3Dtest1%26mynewparam%3Dtest2 and is parsed into $MFD_testparam = test1 and $MFD_mynewparam = test2 macros in the form. Parameter name characters [a-zA-Z0-9], parameter value characters [a-zA-Z0-9], control characters [=&], 2MB max size. For example, this parameter can be used to display payment form in light/dark mode depending on the value passed by Connecting Party (e.g. pass merchant_form_data=theme%3Ddark in request and $MFD_theme macro placeholder on payment form will be changed to dark. | `Necessity`: Optional `Type`: String `Length`: 128 |
| server_callback_url | URL, where the transaction status is sent to. Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to server_callback_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of notify_url. If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). | `Necessity`: Optional `Type`: String `Length`: 1024 |
| notify_url | URL, where the transaction status is sent to. Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to notify_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of server_callback_url. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. | `Necessity`: Optional `Type`: String `Length`: 1024 |
#### Additional Parameters
##### Sender Customer Data
Parameters below can be required for specific integrations. For more information, please contact Support manager.
| Parameter Name | Description | Value |
|-------------------------------------------------|------------------------------------------------------------------------------|------------------------------------------------------|
| sender_first_name | Sender’s first name. | `Type`: String `Length`: 128 |
| sender_last_name | Sender’s last name. | `Type`: String `Length`: 128 |
| sender_middle_name | Sender’s middle name/patronym. | `Type`: String `Length`: 128 |
| sender_ssn | Last four digits of the Sender’s social security number. | `Type`: String `Length`: 11 |
| sender_birth_place | Sender\`s birth place. | `Type`: String `Length`: 128 |
| sender_birthday | Sender’s birthday. | `Type`: String `Length`: 30 |
| sender_address1 | Sender’s address. | `Type`: String `Length`: 256 |
| sender_city | Sender’s city. | `Type`: String `Length`: 128 |
| sender_state | Sender’s US states (two letter abbreviation). Not applicable outside the US. | `Type`: String `Length`: 4 |
| sender_zip_code | Sender\`s zip code. | `Type`: String `Length`: 32 |
| sender_citizenship | Sender\`s citizenship. | `Type`: String `Length`: 128 |
| sender_country_code | Sender’s country (two letter abbreviation). | `Type`: String `Length`: 2 |
| sender_phone | Sender’s full international phone number, including country suffix. | `Type`: String `Length`: 128 |
| sender_cell_phone | Sender’s full international cell phone number, including country suffix. | `Type`: String `Length`: 128 |
| sender_email | Sender’s email address. | `Type`: String `Length`: 128 |
| sender_resident | Is sender a resident? | `Type`: Boolean |
| sender_identity_document_id | Sender\`s identity document name. | `Type`: String `Length`: 128 |
| sender_identity_document_series | Sender\`s identity document series. | `Type`: String `Length`: 12 |
| sender_identity_document_number | Sender\`s identity document number. | `Type`: String `Length`: 16 |
| sender_identity_document_issuer_name | Sender\`s identity document issuer. | `Type`: String `Length`: 128 |
| sender_identity_document_issuer_department_code | Sender\`s identity document issuer department code. | `Type`: String `Length`: 32 |
| sender_identity_document_issue_date | Sender\`s identity document issue date. | `Type`: Date |
##### Receiver Customer Data
Parameters below can be required for specific integrations. For more information, please contact Support manager.
| Parameter Name | Description | Value |
|---------------------------------------------------|-----------------------------------------------------------------------|------------------------------------------------------|
| receiver_first_name | Receiver’s first name. | `Type`: String `Length`: 128 |
| receiver_last_name | Receiver’s last name. | `Type`: String `Length`: 128 |
| receiver_middle_name | Receiver’s middle name/patronym. | `Type`: String `Length`: 128 |
| receiver_birth_place | Receiver\`s birth place. | `Type`: String `Length`: 128 |
| receiver_birthday | Receiver’s birthday. | `Type`: String `Length`: 128 |
| receiver_address1 | Receiver’s address. | `Type`: String `Length`: 256 |
| receiver_city | Receiver’s city. | `Type`: String `Length`: 128 |
| receiver_state | Receiver’s state. | `Type`: String `Length`: 2-4 |
| receiver_zip_code | Receiver\`s zip code. | `Type`: String `Length`: 32 |
| receiver_region | Receiver\`s region. | `Type`: String `Length`: 30 |
| receiver_area | Receiver\`s area. | `Type`: String `Length`: 50 |
| receiver_citizenship | Receiver\`s citizenship. | `Type`: String `Length`: 128 |
| receiver_country_code | Receiver\`s country (two letter abbreviation). | `Type`: String `Length`: 2 |
| receiver_phone | Receiver’s full international phone number, including country suffix. | `Type`: String `Length`: 128 |
| receiver_email | Receiver’s email address. | `Type`: String `Length`: 128 |
| receiver_resident | Is receiver a resident? | `Type`: Boolean |
| receiver_identity_document_id | Receiver\`s identity document name. | `Type`: String `Length`: 128 |
| receiver_identity_document_series | Receiver\`s identity document series. | `Type`: String `Length`: 12 |
| receiver_identity_document_number | Receiver\`s identity document number. | `Type`: String `Length`: 16 |
| receiver_identity_document_issuer_name | Receiver\`s identity document issuer. | `Type`: String `Length`: 128 |
| receiver_identity_document_issuer_department_code | Receiver\`s identity document issuer department code. | `Type`: String `Length`: 32 |
| receiver_identity_document_issue_date | Receiver\`s identity document issue date. | `Type`: Date |
#### Response Parameters
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Parameter | Description. |
|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be async-response, validation-error, error. If type equals validation-error or error, ex:error-message and error-code parameters contain error details. |
| paynet-order-id | Order id assigned to the order by Payneteasy. |
| merchant-order-id | Connecting Party order ID. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
| error-message | If status is error this parameter contains the reason for decline or error details. |
| error-code | The error code is case of error status. |
| redirect-url | The URL to the page where the Connecting Party should redirect the client’s browser. Connecting Party should send HTTP 302 redirect, see General Transfer Form Process Flow. |
#### Request & Response Examples
##### Transfer from Form to PAN
**Request Example**
```http
POST /paynet/api/v4/transfer-form/39915 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth oauth_consumer_key="TestMerchant", oauth_nonce="eZCXwEp9fO17vGFwPUDStKjOKIP9u0nu", oauth_signature="2qrf7DY0fiy88doBrIGafZBqLLX12ePYWDGLqNxwBfU9T3RzwSYtEj92EPuiJulnZxbPY6av4F2jT1JS02D4KqPAtadsEYb8AabBoSvXPK13FrIXKQ38hrcapmXwz%2Fbh0JJBnN3aMvKJ%2FnsvRChY%2FFpRhdudfdBxZLKpAXYfJQgk42%2FB9pu%2FsBSRWJwTnVZxfavHYMWmrY2rvg2x1nedSJq6O%2Fxffz9OU3CvHOlK%2FGfdI4WFvpHIXpw1Mlz%2F6AnQRdMmYHnoDsFu79GI57NeoBRsZazJBYh%2FE%2FFcS9sHU5BF0yvLQYz%2FCXtb7lDbKeDJTHDDWakyyZPQcOQReIMHpNwNr9mjC%2FucIJitFEldsWWGaOnTc2Tqtrdjzzwukm%2BP7Bi5siJ5Pl%2BxWqOMAEFPnCXfThBKIJrxQXbBwR4YfPaBb70nePybCH8JCX0vakoaH%2BwFJfR0WNgOBfYxQfUYNcEXDmrk8hLbwz%2FXJ6bfanFaE8N3OwijJmlzY%2B4ZrEqBjnklQcBnNuvuxKSb6dKtnRo5UVXEszEiCxEvWQifggohkU1CTHZFpA2qmrxjIcgJoDOhQPV6Lk92LiDtVSE2drxZ%2Bjui69ZzGlnKlM0lVCnFfdahrhtMM9GYNN%2B24YaKd5UkCMIMru%2BfOfvqwrJu00%2FIms8VXwsm9aP8pP4Lr3I%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1670421183", oauth_version="1.0"
Content-Length: 303
Content-Type: application/x-www-form-urlencoded
Connection: close
amount=100
&client_orderid=34T43R77N
¤cy=USD
&deposit2card=false
&destination-card-no=4268736646656312
&destination_card_printed_name=Test%20Test
&destination_expire_month=12
&destination_expire_year=2023
&ipaddress=1.1.1.1
&order_desc=Your%20order%20description
&redirect_url=http%3A%2F%2Fwww.example.com
&server_callback_url=https://httpstat.us/200
```
**Success Response Example**
```http
HTTP/1.1 200
Server: server
Date: Wed, 07 Dec 2022 13:56:03 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 285
type=async-form-response
&serial-number=00000000-0000-0000-0000-000002ddbfa2
&merchant-order-id=34T43R77N
&paynet-order-id=6863810
&redirect-url=https%3A%2F%2Fsandbox.payneteasy.eu%2Fpaynet%2Fform%2Finit%2FBB587546567A31587163597A684535634A775969614A577953626976766D4B494A66796F55434370393032673D
```
**Fail Response Example**
```html
HTTP/1.1 403
Server: server
Date: Mon, 12 Dec 2022 08:25:15 GMT
Content-Type: text/html
Content-Length: 735
Connection: close
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
403
Access is denied
```
##### Transfer from Form to RPI
**Request Example**
```http
POST /paynet/api/v4/transfer-form/39915 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth oauth_consumer_key="TestMerchant", oauth_nonce="yQFnx1Zerg4pH28VmLQL3HWc7dQJlAqg", oauth_signature="G2ZRjHOxzhsQ5xIurkM7Bo7REnoBfG3HIDDzwG9XfFGZdFC0815%2FPVS4ESdLPYVEr7iT2K3LtlO2mhMzmIWuRV3YTVKKCbfbuJkPk1OwJOx66ZaX4q0DI5Zej%2FadXiKuJ%2FLe%2BLL8Tp%2Ftzrylk6fiTAoX2AT471hp02xezERVwdEwkhoWB1mqwYE4VxOL8wDk0W0oqR%2Bk1XgWXPcj3E8WV3kEVFwxYwgi6daQyimqReEc5q8fqbUl7sANmIozrSRWqjG2K%2FBLs0W2UFLMcvWdHi2ON%2B%2BnTzaLCExB2991ozSE2jPp4eahkd69Zz%2BEwLENVIn8KDwvA5j25XaGgbqLKK%2BBt5CshObkvZZZ%2FuWqujp%2FzbOBGMuucuwyXe4yW8Ter1YC%2F9zoR%2BMwIcKBd5gaV4mOxQCZ5pe9GMD2805BlM2XDtcB9UT%2FeMs3MR3WIXN51EVCn%2BcazxwEI4LmZ5966aaUGu4GF41JWRQAZBchx4F%2Bd%2BRadwCceBJJSiQg82hwRk4QYnyDEx%2BWqcwErVZGCH8yJhph1Etn3e0G8z0PLBlG2hqTqGPFYivzyFHI1LNW8jl7%2BKJq2HZgXjtcU8Ji%2BVw2JVr86nnM4nPbpIRl7qr%2BSYUpXjWw%2B3e%2F6GtOL%2BOWzVFMo5jKf%2FfyJSdOgbyco1sBHplZRZ8Gsts8UGiIuQ8%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1670847388", oauth_version="1.0"
Content-Length: 213
Content-Type: application/x-www-form-urlencoded
Connection: close
amount=100
&client_orderid=34T43R77N
¤cy=USD
&deposit2card=false
&destination_card_recurring_payment_id=1491854
&ipaddress=1.1.1.1
&order_desc=Your%20order%20description
&redirect_url=http%3A%2F%2Fwww.example.com
&server_callback_url=https://httpstat.us/200
```
**Success Response Example**
```http
HTTP/1.1 200
Server: server
Date: Mon, 12 Dec 2022 12:17:14 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 285
type=async-form-response
&serial-number=00000000-0000-0000-0000-000002ddc2d7
&merchant-order-id=34T43R77N
&paynet-order-id=6863948
&redirect-url=https%3A%2F%2Fsandbox.payneteasy.eu%2Fpaynet%2Fform%2Finit%2FBB587546567A31587163597A684535634A775969614A66354B455A714F6F32684D61414E78767241354872343D
```
**Fail Response Example**
```http
HTTP/1.1 200
Server: server
Date: Mon, 12 Dec 2022 12:08:14 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 132
type=validation-error
&serial-number=00000000-0000-0000-0000-000002ddc2b8
&error-message=Recurring+payment+not+found
&error-code=122
```
##### Transfer from PAN to Form
**Request Example**
```http
POST /paynet/api/v4/transfer-form/39915 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth oauth_consumer_key="TestMerchant", oauth_nonce="BpGsiUR8CbIjGAD1Qxu8MTtGHnlIvzcF", oauth_signature="ozovWc0wjugTlGfrS8TeSxqQtnSEQ7UrGh7z6B5px5BoKgTWF44Ej6VCAxCWMl%2B1Qxg5iZ5ExOqTWZ2GTx70ly%2B%2BgHkSmz3t02PEr9XJsj2%2FOm4XFoF0LnbVPDje7AmZZBuF2l0iandlUBjJVA%2BarD6dWVv8LNrv3RVyheuhBreAr7dLcSD4Iu44MH76tOZS%2BuMnqqFjKwC37owAdC7xtJwOIF8wrFM272qHnzxbfvZRaJruoG6WO%2F%2BMGJLPnaNbrhfJ99%2BtvCybb0CsVMQqJ%2FsUWM8Z89ci6a4MCPE41v1i9lXyvkZDm6qfoVgKVPUHVVsjbvuu5Ub7MeMgBsl76ZrRsi9yLiHmPLQGqhzxydy14GpCNH9FFM2BdRSlkxfBYV1yzX2Ym4gZMq6myvVsCTDgHeGXeQe%2F%2F7z6lLE3S0%2BgcA6NkuhfLU7lvAl0CguRAvU3%2FlVh3R1p8C9S3BXQak6eM0xYp7hO1wQKXMq4uMM2FjmtTUYe6ZiqyjGbkTrrIEkD%2Fo%2FX1NXXylMbWxuNyoTnQXx%2BQzDsUrY3Mhtb%2FslwCGDY4puOlwiVqGg31EBz0wFWzJFX7n2uQO76g5q%2FnTJqf3dq3AdTC6xpaGC2kek0fxc6FEDdaoVeQ3PwJWYi1kcPbwkcvo4gIi03rcO3JUJZF3TfomkFs%2BFnh%2FwLJHs%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1670569138", oauth_version="1.0"
Content-Length: 275
Content-Type: application/x-www-form-urlencoded
Connection: close
amount=100
&card_printed_name=Test%20Test
&client_orderid=34T43R77N
&credit_card_number=4047753518764320
¤cy=USD
&cvv2=123
&deposit2card=false
&expire_month=12
&expire_year=2023
&ipaddress=1.1.1.1
&order_desc=Your%20order%20description
&redirect_url=http%3A%2F%2Fwww.example.com
&server_callback_url=https://httpstat.us/200
```
**Success Response Example**
```http
HTTP/1.1 200
Server: server
Date: Fri, 09 Dec 2022 06:59:20 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 285
type=async-form-response
&serial-number=00000000-0000-0000-0000-000002ddc004
&merchant-order-id=34T43R77N
&paynet-order-id=6863822
&redirect-url=https%3A%2F%2Fsandbox.payneteasy.eu%2Fpaynet%2Fform%2Finit%2FBB587546567A31587163597A684535634A775969614A61365A5A5637456C4545743867705438697A512F30633D
```
**Fail Response Example**
```html
HTTP/1.1 403
Server: server
Date: Fri, 09 Dec 2022 06:45:14 GMT
Content-Type: text/html
Content-Length: 735
Connection: close
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
403
Access is denied
```
##### Transfer from RPI to Form
**Request Example**
```http
POST /paynet/api/v4/transfer-form/39915 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth oauth_consumer_key="TestMerchant", oauth_nonce="y03UAVaLM9NXEwAHD0R9YDCQQFzRWx8b", oauth_signature="Zgx05s2b%2Fr4wSbo0sb2tGXbhPeDYlfJfnziSH57mkYfEMNtGoWCeUlLanQLKq1ddusIBhGUFwpwoh5f22y9tqHRsekiAQ92s9ixQxmvE8sEV3Ov%2FHoTyktrxN0vhPxuwSmwD%2FhX%2FOMJgDaCoOZK%2BxeXfPRVRwlNM8LsDd29i%2FnIUsExWCBujs3M5ThYGz58UJdZmOxrWW3poH2Lb6Fw9b6XMwV2DzvyomhMzZfyQYYX%2BhP22rCmXTg%2BEyTVnJDBiWI3pF6WYQFjdO5tPbcK4bxw4IYNIKKEi78dw0%2FZcb65gfHlaUtqHd3ZXiFiob4YFeV%2B1XKI2wSVBVemEd3jVjOFXDZv2GLzrZOUkxcns6BqkRxMqaWc9%2FbpsL65XdFxB4LUuP2h1PVk6A5yjjanSjp1XqzyAx8EGpxYGAzIPNSsYPVN9x5TuyIqtYVXhz2y0z8RPx5VFmSYr%2BaCr6ruhRNkyonNmk47oPkIkG9PpLivBaq8PnIzUNpExTRIYJXJOwD69CjCPxT%2Fhr3udDQJD4ZHFE3TNA9g1H0VRL%2Ff60jPhZeanf9MgcFqz6jckPQghBixOaTBf9DmP9jmv12IQZ3PR3J3n53nDEUIw%2Fhiga3%2BdZswkJMYS57VB282SVfDXQPO%2F40OC%2B3annev%2BMftiSfChhRgazDRToCnbETXqoKc%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1670850681", oauth_version="1.0"
Content-Length: 266
Content-Type: application/x-www-form-urlencoded
Connection: close
amount=100
&card_recurring_payment_id=1491854
&client_orderid=34T43R77N
¤cy=USD
&cvv2=123
&deposit2card=false
&ipaddress=1.1.1.1
&order_desc=Your%20order%20description
&redirect_url=http%3A%2F%2Fwww.example.com
&server_callback_url=https://httpstat.us/200
```
**Success Response Example**
```http
HTTP/1.1 200
Server: server
Date: Mon, 12 Dec 2022 13:12:21 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 285
type=async-form-response
&serial-number=00000000-0000-0000-0000-000002ddc34e
&merchant-order-id=34T43R77N
&paynet-order-id=6863959
&redirect-url=https%3A%2F%2Fsandbox.payneteasy.eu%2Fpaynet%2Fform%2Finit%2FBB587546567A31587163597A684535634A775969614A5A716755336669466574615739747A737059777A50493D
```
**Fail Response Example**
```http
HTTP/1.1 200
Server: server
Date: Mon, 12 Dec 2022 12:25:05 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 176
type=validation-error
&serial-number=00000000-0000-0000-0000-000002ddc2ec
&merchant-order-id=34T43R77N
&error-message=Src+card+cvv2+should+be+filled+in+transfer.
&error-code=29
```
##### Transfer from Form to Form
**Request Example**
```http
POST /paynet/api/v4/transfer-form/39915 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth oauth_consumer_key="TestMerchant", oauth_nonce="3FUX1QCRBPF7am99UO4bty1qD7FK08I8", oauth_signature="CCvlgjfVBZOwoMS%2FbUXv1LiRlc0Nu3Owf3FwNmPnbP49RWi3ve3VE9Jt61QpRx14pmCz3xFKQt%2Bi4UvXJYlsn206TSZ9H7TGCSHhQQP5vD0mm3Pnq0YgtI2oPpn2PhgM%2FlgwwWcBjBqmCyzM%2FGGqK24zn5C20bxvHL9LfuMgF4bEpIYDGXVh3%2BbhlU5Z2H25fjjttZylm1SLhAi9lOct2%2BtH00TJ%2FgjdWR%2FCnIroLVPWqnYbE8f%2F%2Bz1HuynqW684UUaAiB8WgEulH1BBM6HqYiFAVyfWlLNzDv08cKZew7JPsso17XBdqYyE2QWkREM61FPSQpQsuAnRpezxjRZnmxsShXKqgNwj%2B%2BVeEEP7Z0IFqUreDgSYYSntrgtvZHhX6oNuEn4V8jWA6TO0wPNPKqkEXTk7w53nF0Hn%2FLgAa3FfYSHtCnFP1uELmPnVrO03IWaPPw0%2BcCJzNMua7g%2FYjlCsdV3tlwUwne1R0V3togR5k%2FTnG%2Bub4txjaFeqOm9p517ppKZQn8Fe0jtIIJMCYVRVmsYkeBZyyRgcdIBOAn09fCKZ7y74gI12py%2FvVzagFCjZo05T20gY6OpCkrP4HhWEkKJhrqSCBe7NLC1xZDszfkLFjF9Z4dWvk2PIcNfI3SGYZRks0YFPECycfYzYIJfuKplYAACzR47h30SaOiI%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1670835177", oauth_version="1.0"
Content-Length: 167
Content-Type: application/x-www-form-urlencoded
Connection: close
amount=100
&client_orderid=34T43R77N
¤cy=USD
&deposit2card=false
&ipaddress=1.1.1.1
&order_desc=Your%20order%20description
&redirect_url=http%3A%2F%2Fwww.example.com
&server_callback_url=https://httpstat.us/200
```
**Success Response Example**
```http
HTTP/1.1 200
Server: server
Date: Mon, 12 Dec 2022 08:53:26 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 285
type=async-form-response
&serial-number=00000000-0000-0000-0000-000002ddc1f8
&merchant-order-id=34T43R77N
&paynet-order-id=6863917
&redirect-url=https%3A%2F%2Fsandbox.payneteasy.eu%2Fpaynet%2Fform%2Finit%2FBB587546567A31587163597A684535634A775969614A613368326D746C2B72645043314744502B537A6E57343D
```
**Fail Response Example**
```html
HTTP/1.1 403
Server: server
Date: Mon, 12 Dec 2022 09:18:33 GMT
Content-Type: text/html
Content-Length: 735
Connection: close
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
403
Access is denied
```
##### Transfer from Deposit to Form
**Request Example**
```http
POST /paynet/api/v4/transfer-form/39915 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth oauth_consumer_key="TestMerchant", oauth_nonce="SDrbaim155azbf2UthcVDrhwiOA6liE4", oauth_signature="CFUUC1Y6QT5Gj7LA%2FdW6gkGN%2Fh73J8HAxhvYtFx%2F%2FChlQIU7f4uvVmKpOossrRD05wdx0ENHJZLZ8SI%2B610ygcWP%2B3K%2FqEYDI7qjdg8HgKlT3BnjSoGU6EjGjvcMwQSY0AwNJ4adYYZG6G%2Ble9SOvbPcQalkfxIjpTl%2FkyrIVtNS4h9ExkD%2Fg9UUXZ%2F2YAOCyhTy26QwOLOo5NmNeh%2FX7wpqPEyjHfEE%2FWbc3iSNSjlJA9b%2BfX5eFAVxzzZ2X76HRxy%2FuHqah9NszgXsagMHpXOpvovNRLEh7NFBqVDWhoHFfDS%2Bwd6vcLqXxwLKOVecmq06GN1%2BiZX4C9QebaNw6JSx72jMon3hnn37pUSLhzWXz%2BwlMX7XN%2FcTWsZ0kL51DzFXwPAJPVAeNevgxlaFtbELMGcZNOU19u72cOZKMu7%2FsxLAfCgUITCO2NhvZw%2BR8xUZUcxvwu4fvoTXr6rf8r0iloJIA9RoaKobzmPUDcGx3%2F4Hswjbqk7YOg6jxQJD6ZoKscHpLiQLvBWPILsSVMpQUpnUqzBNGexdCd8zaRzqiszwz4hEg6teTMFOLA%2FoQ8Wu%2FxtSs8JMuXsWtestY9h1y5KuXWDy8O9hpN45pBF%2BvtoDfyr6ktKrkZZTZG49FBKk%2FcKi5FjzL5Bsbwv9fgk1%2BRYDexMtHCqX%2Fdrz%2BzMM%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1670851416", oauth_version="1.0"
Content-Length: 166
Content-Type: application/x-www-form-urlencoded
Connection: close
amount=100
&client_orderid=34T43R77N
¤cy=USD
&deposit2card=true
&ipaddress=1.1.1.1
&order_desc=Your%20order%20description
&redirect_url=http%3A%2F%2Fwww.example.com
&server_callback_url=https://httpstat.us/200
```
**Success Response Example**
```http
HTTP/1.1 200
Server: server
Date: Mon, 12 Dec 2022 13:23:58 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 285
type=async-form-response
&serial-number=00000000-0000-0000-0000-000002ddc35a
&merchant-order-id=34T43R77N
&paynet-order-id=6863960
&redirect-url=https%3A%2F%2Fsandbox.payneteasy.eu%2Fpaynet%2Fform%2Finit%2FBB587546567A31587163597A684535634A775969614A5878476D6E717A31324167486F61674C6830743070343D
```
**Fail Response Example**
```html
HTTP/1.1 403
Server: server
Date: Mon, 12 Dec 2022 13:19:46 GMT
Content-Type: text/html
Content-Length: 735
Connection: close
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
403
Access is denied
```
### /api/v4/transfer
#### Introduction
Transfer is a type of complex transaction that allows to move funds between bank cards (Primary Account Number - PAN), card tokens (Recurring Payment ID - RPI) and Connecting Party bank account (deposits).
Transfer is initiated through HTTPS POST request to the [URL](#transfer-api-urls) with the [required parameters](#transfer-request-parameters-description) depending on a certain transfer Use-Case (see below). Some integrations might require [Additional parameters](#transfer-additional-parameters). Use [OAuth RSA-SHA256](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md) for authentication.
Possible transfer Use-Cases:
| PAN to PAN | Transfer from PAN to PAN occurs when transferring funds from one bank card to another, when specifying for each card their card numbers, and not the recurring payment id. |
|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| PAN to RPI | Transfer from PAN to RPI occurs when funds are transferred from one bank card for which its number is indicated to another bank card for which its recurring payment id is indicated. |
| RPI to PAN | Transfer from RPI to PAN occurs when funds are transferred from one bank card for which its recurring payment id is indicated to another bank card for which its number is indicated. |
| RPI to RPI | Transfer from RPI to RPI occurs when transferring funds from one bank card to another, when specifying for each card their recurring payment id, and not the card number. |
| Deposit to PAN | Deposit Transfer to PAN occurs when funds are transferred from Connecting Party account to a bank card by its number. |
| Deposit to RPI | Deposit Transfer to RPI occurs when funds are transferred from Connecting Party account to a bank card by recurring payment id. |
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|----------------------------------------------------------------------------|-------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v4/transfer/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v4/transfer/ENDPOINTID |
| https://sandbox.payneteasy.eu/paynet/api/v4/transfer/group/ENDPOINTGROUPID | https://gate.payneteasy.eu/paynet/api/v4/transfer/group/ENDPOINTGROUPID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded and [Authorization headers](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md).
PAN to PAN
| Parameter | Description | Value |
|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| credit_card_number | Sender\`s credit card number. For the scenario of payment from a card inside the system, this card will be considered as a source. | `Necessity`: Required `Type`: Numeric `Length`: 19 |
| cvv2 | Sender\`s CVV2 code. CVV2 (Card verification value) is the three of four-digit number farthest to the right on the flip side of a credit card. | `Necessity`: Required `Type`: String `Length`: 3-4 |
| expire_month | Sender credit card’s month of expiration. | `Necessity`: Required `Type`: String `Length`: 2 |
| expire_year | Sender credit card’s year of expiration. | `Necessity`: Required `Type`: String `Length`: 2-4 |
| card_printed_name | Sender\`s card printed name. | `Necessity`: Required `Type`: String `Length`: 128 |
| destination-card-no | Receiver\`s card PAN. For the scenario of payment to a card inside the system, this card will be considered as a destination, and all processing limits, lists and fraud scoring will be applied to it as a destination card. | `Necessity`: Required `Type`: Numeric `Length`: 19 |
| deposit2card | Marker of Deposit to Card transfer. If true, no sender cardholder data is needed to process the transaction. If false, sender cardholder data is needed. | `Value`: False `Type`: Boolean |
| destination_expire_month | Receiver credit card’s month of expiration. | `Necessity`: Optional `Type`: String `Length`: 2 |
| destination_expire_year | Receiver credit card’s year of expiration. | `Necessity`: Optional `Type`: String `Length`: 2-4 |
| destination_card_printed_name | Receiver\`s card printed name. | `Necessity`: Optional `Type`: String `Length`: 128 |
| ipaddress | The Sender or Receiver’s IP address, include for fraud screening purposes. NB: 45 is for IPv4 tunneling like 0000:0000:0000:0000:0000:0000:192.168.100.101 | `Necessity`: Required `Type`: String `Length`: 7-45 |
| client_orderid | Connecting Party order ID. | `Necessity`: Required `Type`: String `Length`: 128 |
| currency | Currency the transaction is charged in (three-letter currency code). Example of valid parameter values are: USD for US Dollar, EUR for European Euro. | `Necessity`: Required `Type`: String `Length`: 3 |
| amount | Amount to be transferred. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. | `Necessity`: Required `Type`: Numeric `Length`: 10 |
| purpose | Destination to where the payment goes. It is useful for the Connecting Party who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account. Sample values are: +9999999999; [mail@example.com](mailto:mail@example.com) etc. This value will be used by fraud monitoring system | `Necessity`: Optional `Type`: String `Length`: 128 |
| redirect_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved, declined or in any other final status. Optional for direct integration (non-form) deposit2card. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| order_desc | Order description. | `Necessity`: Required `Type`: String `Length`: 64k |
| server_callback_url | URL, where the transaction status is sent to. Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to server_callback_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of notify_url. If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). | `Necessity`: Optional `Type`: String `Length`: 1024 |
| notify_url | URL, where the transaction status is sent to. Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to notify_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of server_callback_url. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. | `Necessity`: Optional `Type`: String `Length`: 1024 |
PAN to RPI
| Parameter | Description | Value |
|---------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| credit_card_number | Sender\`s credit card number. For the scenario of payment from a card inside the system, this card will be considered as a source. | `Necessity`: Required `Type`: Numeric `Length`: 19 |
| cvv2 | Sender\`s CVV2 code. CVV2 (Card verification value) is the three of four-digit number farthest to the right on the flip side of a credit card. | `Necessity`: Required `Type`: String `Length`: 3-4 |
| expire_month | Sender credit card’s month of expiration. | `Necessity`: Required `Type`: String `Length`: 2 |
| expire_year | Sender credit card’s year of expiration. | `Necessity`: Required `Type`: String `Length`: 2-4 |
| card_printed_name | Sender\`s card printed name. | `Necessity`: Required `Type`: String `Length`: 128 |
| deposit2card | Marker of Deposit to Card transfer. If true, no sender cardholder data is needed to process the transaction. If false, sender cardholder data is needed. | `Value`: False `Type`: Boolean |
| destination_card_recurring_payment_id | Receiver\`s recurring payment ID. To create destination_card_recurring_payment_id please see [Card Reference ID Creation](https://doc.payneteasy.com/integration/api_v4_create-card-ref.html.md). For the scenario of payment to a card inside the system, this card will be considered as a destination, and all processing limits, lists and fraud scoring will be applied to it as a destination card. | `Necessity`: Required `Type`: Long |
| ipaddress | The Sender or Receiver’s IP address, include for fraud screening purposes. NB: 45 is for IPv4 tunneling like 0000:0000:0000:0000:0000:0000:192.168.100.101 | `Necessity`: Required `Type`: String `Length`: 7-45 |
| client_orderid | Connecting Party order ID. | `Necessity`: Required `Type`: String `Length`: 128 |
| currency | Currency the transaction is charged in (three-letter currency code). Example of valid parameter values are: USD for US Dollar, EUR for European Euro. | `Necessity`: Required `Type`: String `Length`: 3 |
| amount | Amount to be transferred. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. | `Necessity`: Required `Type`: Numeric `Length`: 10 |
| purpose | Destination to where the payment goes. It is useful for the Connecting Party who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account. Sample values are: +9999999999; [mail@example.com](mailto:mail@example.com) etc. This value will be used by fraud monitoring system | `Necessity`: Optional `Type`: String `Length`: 128 |
| redirect_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved, declined or in any other final status. Optional for direct integration (non-form) deposit2card. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| order_desc | Order description. | `Necessity`: Required `Type`: String `Length`: 64k |
| server_callback_url | URL, where the transaction status is sent to. Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to server_callback_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of notify_url. If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). | `Necessity`: Optional `Type`: String `Length`: 1024 |
| notify_url | URL, where the transaction status is sent to. Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to notify_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of server_callback_url. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. | `Necessity`: Optional `Type`: String `Length`: 1024 |
RPI to PAN
| Parameter | Description | Value |
|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| destination-card-no | Receiver\`s card PAN. For the scenario of payment to a card inside the system, this card will be considered as a destination, and all processing limits, lists and fraud scoring will be applied to it as a destination card. | `Necessity`: Required `Type`: Numeric `Length`: 19 |
| deposit2card | Marker of Deposit to Card transfer. If true, no sender cardholder data is needed to process the transaction. If false, sender cardholder data is needed. | `Value`: False `Type`: Boolean |
| cvv2 | Sender\`s CVV2 code. CVV2 (Card verification value) is the three of four-digit number farthest to the right on the flip side of a credit card. | `Necessity`: Required `Type`: String `Length`: 3-4 |
| destination_expire_month | Receiver credit card’s month of expiration. | `Necessity`: Optional `Type`: String `Length`: 2 |
| destination_expire_year | Receiver credit card’s year of expiration. | `Necessity`: Optional `Type`: String `Length`: 2-4 |
| destination_card_printed_name | Receiver\`s card printed name. | `Necessity`: Optional `Type`: String `Length`: 128 |
| card_recurring_payment_id | Sender\`s recurring payment ID. To create card_recurring_payment_id please see Card Reference ID Creation. For the scenario of payment from a card inside the system, this card will be considered as a source. | `Necessity`: Required `Type`: Long |
| ipaddress | The Sender or Receiver’s IP address, include for fraud screening purposes. NB: 45 is for IPv4 tunneling like 0000:0000:0000:0000:0000:0000:192.168.100.101 | `Necessity`: Required `Type`: String `Length`: 7-45 |
| client_orderid | Connecting Party order ID. | `Necessity`: Required `Type`: String `Length`: 128 |
| currency | Currency the transaction is charged in (three-letter currency code). Example of valid parameter values are: USD for US Dollar, EUR for European Euro. | `Necessity`: Required `Type`: String `Length`: 3 |
| amount | Amount to be transferred. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. | `Necessity`: Required `Type`: Numeric `Length`: 10 |
| purpose | Destination to where the payment goes. It is useful for the Connecting Party who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account. Sample values are: +9999999999; [mail@example.com](mailto:mail@example.com) etc. This value will be used by fraud monitoring system | `Necessity`: Optional `Type`: String `Length`: 128 |
| redirect_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved, declined or in any other final status. Optional for direct integration (non-form) deposit2card. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| order_desc | Order description. | `Necessity`: Required `Type`: String `Length`: 64k |
| server_callback_url | URL, where the transaction status is sent to. Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to server_callback_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of notify_url. If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). | `Necessity`: Optional `Type`: String `Length`: 1024 |
| notify_url | URL, where the transaction status is sent to. Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to notify_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of server_callback_url. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. | `Necessity`: Optional `Type`: String `Length`: 1024 |
RPI to RPI
| Parameter | Description | Value |
|---------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| deposit2card | Marker of Deposit to Card transfer. If true, no sender cardholder data is needed to process the transaction. If false, sender cardholder data is needed. | `Value`: False `Type`: Boolean |
| cvv2 | Sender\`s CVV2 code. CVV2 (Card verification value) is the three of four-digit number farthest to the right on the flip side of a credit card. | `Necessity`: Required `Type`: String `Length`: 3-4 |
| destination_card_recurring_payment_id | Receiver\`s recurring payment ID. To create destination_card_recurring_payment_id please see [Card Reference ID Creation](https://doc.payneteasy.com/integration/api_v4_create-card-ref.html.md). For the scenario of payment to a card inside the system, this card will be considered as a destination, and all processing limits, lists and fraud scoring will be applied to it as a destination card. | `Necessity`: Required `Type`: Long |
| card_recurring_payment_id | Sender\`s recurring payment ID. To create card_recurring_payment_id please see Card Reference ID Creation. For the scenario of payment from a card inside the system, this card will be considered as a source. | `Necessity`: Required `Type`: Long |
| ipaddress | The Sender or Receiver’s IP address, include for fraud screening purposes. NB: 45 is for IPv4 tunneling like 0000:0000:0000:0000:0000:0000:192.168.100.101 | `Necessity`: Required `Type`: String `Length`: 7-45 |
| client_orderid | Connecting Party order ID. | `Necessity`: Required `Type`: String `Length`: 128 |
| currency | Currency the transaction is charged in (three-letter currency code). Example of valid parameter values are: USD for US Dollar, EUR for European Euro. | `Necessity`: Required `Type`: String `Length`: 3 |
| amount | Amount to be transferred. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. | `Necessity`: Required `Type`: Numeric `Length`: 10 |
| purpose | Destination to where the payment goes. It is useful for the Connecting Party who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account. Sample values are: +9999999999; [mail@example.com](mailto:mail@example.com) etc. This value will be used by fraud monitoring system | `Necessity`: Optional `Type`: String `Length`: 128 |
| redirect_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved, declined or in any other final status. Optional for direct integration (non-form) deposit2card. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| order_desc | Order description. | `Necessity`: Required `Type`: String `Length`: 64k |
| server_callback_url | URL, where the transaction status is sent to. Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to server_callback_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of notify_url. If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). | `Necessity`: Optional `Type`: String `Length`: 1024 |
| notify_url | URL, where the transaction status is sent to. Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to notify_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of server_callback_url. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. | `Necessity`: Optional `Type`: String `Length`: 1024 |
Deposit to PAN
| Parameter | Description | Value |
|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| destination-card-no | Receiver\`s card PAN. For the scenario of payment to a card inside the system, this card will be considered as a destination, and all processing limits, lists and fraud scoring will be applied to it as a destination card. | `Necessity`: Required `Type`: Numeric `Length`: 19 |
| deposit2card | Marker of Deposit to Card transfer. If true, no sender cardholder data is needed to process the transaction. If false, sender cardholder data is needed. | `Value`: True `Type`: Boolean |
| destination_expire_month | Receiver credit card’s month of expiration. | `Necessity`: Optional `Type`: String `Length`: 2 |
| destination_expire_year | Receiver credit card’s year of expiration. | `Necessity`: Optional `Type`: String `Length`: 2-4 |
| destination_card_printed_name | Receiver\`s card printed name. | `Necessity`: Optional `Type`: String `Length`: 128 |
| ipaddress | The Sender or Receiver’s IP address, include for fraud screening purposes. NB: 45 is for IPv4 tunneling like 0000:0000:0000:0000:0000:0000:192.168.100.101 | `Necessity`: Required `Type`: String `Length`: 7-45 |
| client_orderid | Connecting Party order ID. | `Necessity`: Required `Type`: String `Length`: 128 |
| currency | Currency the transaction is charged in (three-letter currency code). Example of valid parameter values are: USD for US Dollar, EUR for European Euro. | `Necessity`: Required `Type`: String `Length`: 3 |
| amount | Amount to be transferred. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. | `Necessity`: Required `Type`: Numeric `Length`: 10 |
| purpose | Destination to where the payment goes. It is useful for the Connecting Party who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account. Sample values are: +9999999999; [mail@example.com](mailto:mail@example.com) etc. This value will be used by fraud monitoring system | `Necessity`: Optional `Type`: String `Length`: 128 |
| redirect_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved, declined or in any other final status. Optional for direct integration (non-form) deposit2card. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| order_desc | Order description. | `Necessity`: Required `Type`: String `Length`: 64k |
| server_callback_url | URL, where the transaction status is sent to. Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to server_callback_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of notify_url. If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). | `Necessity`: Optional `Type`: String `Length`: 1024 |
| notify_url | URL, where the transaction status is sent to. Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to notify_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of server_callback_url. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. | `Necessity`: Optional `Type`: String `Length`: 1024 |
Deposit to RPI
| Parameter | Description | Value |
|---------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| deposit2card | Marker of Deposit to Card transfer. If true, no sender cardholder data is needed to process the transaction. If false, sender cardholder data is needed. | `Value`: True `Type`: Boolean |
| destination_card_recurring_payment_id | Receiver\`s recurring payment ID. To create destination_card_recurring_payment_id please see [Card Reference ID Creation](https://doc.payneteasy.com/integration/api_v4_create-card-ref.html.md). For the scenario of payment to a card inside the system, this card will be considered as a destination, and all processing limits, lists and fraud scoring will be applied to it as a destination card. | `Necessity`: Required `Type`: Long |
| ipaddress | The Sender or Receiver’s IP address, include for fraud screening purposes. NB: 45 is for IPv4 tunneling like 0000:0000:0000:0000:0000:0000:192.168.100.101 | `Necessity`: Required `Type`: String `Length`: 7-45 |
| client_orderid | Connecting Party order ID. | `Necessity`: Required `Type`: String `Length`: 128 |
| currency | Currency the transaction is charged in (three-letter currency code). Example of valid parameter values are: USD for US Dollar, EUR for European Euro. | `Necessity`: Required `Type`: String `Length`: 3 |
| amount | Amount to be transferred. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. | `Necessity`: Required `Type`: Numeric `Length`: 10 |
| purpose | Destination to where the payment goes. It is useful for the Connecting Party who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account. Sample values are: +9999999999; [mail@example.com](mailto:mail@example.com) etc. This value will be used by fraud monitoring system | `Necessity`: Optional `Type`: String `Length`: 128 |
| redirect_url | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved, declined or in any other final status. Optional for direct integration (non-form) deposit2card. | `Necessity`: Optional `Type`: String `Length`: 1024 |
| order_desc | Order description. | `Necessity`: Required `Type`: String `Length`: 64k |
| server_callback_url | URL, where the transaction status is sent to. Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to server_callback_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of notify_url. If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). | `Necessity`: Optional `Type`: String `Length`: 1024 |
| notify_url | URL, where the transaction status is sent to. Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to notify_url refer to [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). This parameter can be sent instead of server_callback_url. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. | `Necessity`: Optional `Type`: String `Length`: 1024 |
#### Additional Parameters
##### For Connecting Party
Use additional parameters for Connecting Party to specify Sender’s browser information and Connecting Party 3DS results notification URL.
The Connecting Party’s site needs to accurately populate the browser information for each transaction. This data can be obtained by Connecting Party’s servers. Ensure that the data is not altered or hard-coded, and that it is unique to each transaction.
> **Note:** These parameters are not applicable for cases `Deposit to PAN` and `Deposit to RPI`.
> **Note:** Browser data for 3DS 2. X is gathered by payment gateway system on 3DS authentication stage. For some processing channels, however, the browser data and/or connecting party URL for 3DS challenge results must be provided in initial transaction request. Please contact Support manager to clarify if these parameters should be included in request parameters.
| Parameter Name | Description | Value |
|---------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------|
| tds_areq_notification_url, alias tds_cres_notification_url | Fully qualified URL of Connecting Party system that will receive the CRes message or Error Message. This CRes message must be sent to Payneteasy. See details here [Upload CRes Result](https://doc.payneteasy.com/integration/upload-cres-result.html.md). | `Type`: String `Length`: 256 |
| customer_browser_info | If true, then the fields below must be present. | `Type`: Boolean |
| ipaddress | IP address of the browser as returned by the HTTP headers to the 3DS Requestor. | `Type`: String `Length`: 45 |
| customer_browser_accept_header, alias customer_accept | Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser. | `Type`: String `Length`: 2048 |
| customer_browser_color_depth | Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Required when browser_java Script_enabled=true. | `Type`: String `Length`: 2 |
| customer_browser_java_enabled | Boolean that represents the ability of the cardholder browser to execute Java. Required when browser_java Script_enabled=true. | `Type`: Boolean |
| customer_browser_javascript_enabled | Boolean that represents the ability of the cardholder browser to execute Java Script. | `Type`: Boolean |
| customer_browser_accept_language, alias customer_accept_language | Value representing the browser language as defined in IETF BCP47. | `Type`: String `Length`: 8 |
| customer_browser_screen_height | Total height of the Cardholder’s screen in pixels. Required when browser_java Script_enabled=true. | `Type`: Numeric `Length`: 6 |
| customer_browser_screen_width | Total width of the Cardholder’s screen in pixels. Required when browser_java Script_enabled=true. | `Type`: Numeric `Length`: 6 |
| customer_browser_time_zone | Time-zone offset in minutes between UTC and the Cardholder browser local time. Note that the offset is positive if the local time zone is behind UTC and negative if it is ahead. Required when browser_java Script_enabled=true. | `Type`: String `Length`: 5 |
| customer_browser_user_agent | Exact content of the HTTP user-agent header. | `Type`: String `Length`: 2048 |
##### For Payment Institutions
The Payment Institution can fill the 3DS results for each transaction, if 3DS authentication is performed on their side.
> **Note:** These parameters are not applicable for cases `Deposit to PAN` and `Deposit to RPI`.
| Parameter Name | Description | Value |
|------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------|
| tds_authentication_result_type | Type of result. Possible value is: SIMPLE | `Type`: String `Length`: 6 |
| tds_authentication_result_authentication_type | Authentication Type. Indicates the type of authentication method the Issuer will use to challenge the Cardholder, whether in the ARes message or what was used by the ACS when in the RReq message. Possible values are: * 01 = Static. * 02 = Dynamic. * 03 = OOB. * 04 = Decoupled. * 05-79 = Reserved for EMVCo future use (values invalid until defined by EMVCo). * 80-99 = Reserved for DS use. | `Type`: String `Length`: 2 |
| tds_authentication_result_authentication_value | Authentication Value. Payment System-specific value provided by the ACS or the DS using an algorithm defined by Payment System. Authentication Value may be used to provide proof of authentication. A 20-byte value that has been Base64 encoded, giving a 28-byte result. | `Type`: String `Length`: 19-28 |
| tds_authentication_result_transaction_id | xid for 1.0.2 or ds TransID for 2.1.0/2.2.0. | `Type`: String `Length`: 19-36 |
| tds_authentication_result_transaction_status | Transaction Status. Indicates whether a transaction qualifies as an authenticated transaction or account verification. Possible values are: * Y = Authentication Verification Successful. * N = Not Authenticated/Account Not Verified, Transaction denied. * U = Authentication/Account Verification Could Not Be Performed, Technical or other problem, as indicated in ARes or RReq. * A = Attempts Processing Performed, Not Authenticated/Verified, but a proof of attempted authentication/verification is provided. * C = Challenge Required, Additional authentication is required using the CReq/CRes. * D = Challenge Required, Decoupled Authentication confirmed. * R = Authentication/ Account Verification Rejected, Issuer is rejecting. | `Type`: String `Length`: 1 |
| tds_authentication_result_message_version | Message Version Number. Protocol version identifier This shall be the Protocol Version Number of the specification utilised by the system creating this message. The Message Version Number is set by the 3DS Server which originates the protocol with the AReq message. The Message Version Number does not change during a 3DS transaction. Possible values are: * 1.0.2 * 2.1.0 * 2.2.0 | `Type`: String `Length`: 5 |
##### Sender Customer Data
Parameters below can be required for specific integrations. For more information, please contact Support manager.
| Parameter Name | Description | Value |
|-------------------------------------------------|------------------------------------------------------------------------------|------------------------------------------------------|
| sender_first_name | Sender’s first name. | `Type`: String `Length`: 128 |
| sender_last_name | Sender’s last name. | `Type`: String `Length`: 128 |
| sender_middle_name | Sender’s middle name/patronym. | `Type`: String `Length`: 128 |
| sender_ssn | Last four digits of the Sender’s social security number. | `Type`: String `Length`: 11 |
| sender_birth_place | Sender\`s birth place. | `Type`: String `Length`: 128 |
| sender_birthday | Sender’s birthday. | `Type`: String `Length`: 30 |
| sender_address1 | Sender’s address. | `Type`: String `Length`: 256 |
| sender_city | Sender’s city. | `Type`: String `Length`: 128 |
| sender_state | Sender’s US states (two letter abbreviation). Not applicable outside the US. | `Type`: String `Length`: 4 |
| sender_zip_code | Sender\`s zip code. | `Type`: String `Length`: 32 |
| sender_citizenship | Sender\`s citizenship. | `Type`: String `Length`: 128 |
| sender_country_code | Sender’s country (two letter abbreviation). | `Type`: String `Length`: 2 |
| sender_phone | Sender’s full international phone number, including country suffix. | `Type`: String `Length`: 128 |
| sender_cell_phone | Sender’s full international cell phone number, including country suffix. | `Type`: String `Length`: 128 |
| sender_email | Sender’s email address. | `Type`: String `Length`: 128 |
| sender_resident | Is sender a resident? | `Type`: Boolean |
| sender_identity_document_id | Sender\`s identity document name. | `Type`: String `Length`: 128 |
| sender_identity_document_series | Sender\`s identity document series. | `Type`: String `Length`: 12 |
| sender_identity_document_number | Sender\`s identity document number. | `Type`: String `Length`: 16 |
| sender_identity_document_issuer_name | Sender\`s identity document issuer. | `Type`: String `Length`: 128 |
| sender_identity_document_issuer_department_code | Sender\`s identity document issuer department code. | `Type`: String `Length`: 32 |
| sender_identity_document_issue_date | Sender\`s identity document issue date. | `Type`: Date |
##### Receiver Customer Data
Parameters below can be required for specific integrations. For more information, please contact Support manager.
| Parameter Name | Description | Value |
|---------------------------------------------------|-----------------------------------------------------------------------|------------------------------------------------------|
| receiver_first_name | Receiver’s first name. | `Type`: String `Length`: 128 |
| receiver_last_name | Receiver’s last name. | `Type`: String `Length`: 128 |
| receiver_middle_name | Receiver’s middle name/patronym. | `Type`: String `Length`: 128 |
| receiver_birth_place | Receiver\`s birth place. | `Type`: String `Length`: 128 |
| receiver_birthday | Receiver’s birthday. | `Type`: String `Length`: 128 |
| receiver_address1 | Receiver’s address. | `Type`: String `Length`: 256 |
| receiver_city | Receiver’s city. | `Type`: String `Length`: 128 |
| receiver_state | Receiver’s state. | `Type`: String `Length`: 2-4 |
| receiver_zip_code | Receiver\`s zip code. | `Type`: String `Length`: 32 |
| receiver_region | Receiver\`s region. | `Type`: String `Length`: 30 |
| receiver_area | Receiver\`s area. | `Type`: String `Length`: 50 |
| receiver_citizenship | Receiver\`s citizenship. | `Type`: String `Length`: 128 |
| receiver_country_code | Receiver\`s country (two letter abbreviation). | `Type`: String `Length`: 2 |
| receiver_phone | Receiver’s full international phone number, including country suffix. | `Type`: String `Length`: 128 |
| receiver_email | Receiver’s email address. | `Type`: String `Length`: 128 |
| receiver_resident | Is receiver a resident? | `Type`: Boolean |
| receiver_identity_document_id | Receiver\`s identity document name. | `Type`: String `Length`: 128 |
| receiver_identity_document_series | Receiver\`s identity document series. | `Type`: String `Length`: 12 |
| receiver_identity_document_number | Receiver\`s identity document number. | `Type`: String `Length`: 16 |
| receiver_identity_document_issuer_name | Receiver\`s identity document issuer. | `Type`: String `Length`: 128 |
| receiver_identity_document_issuer_department_code | Receiver\`s identity document issuer department code. | `Type`: String `Length`: 32 |
| receiver_identity_document_issue_date | Receiver\`s identity document issue date. | `Type`: Date |
#### Response Parameters
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Parameter | Description |
|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. May be async-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details. |
| paynet-order-id | Order id assigned to the order by Payneteasy. |
| merchant-order-id | Connecting Party order ID. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
| error-message | If status is error this parameter contains the reason for decline or error details. |
| error-code | The error code is case of error status. |
| end-point-id | Endpoint id used for the transaction. |
#### Request & Response Examples
##### Transfer from PAN to PAN
**Request Example**
```http
POST /paynet/api/v4/transfer/39509 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth oauth_consumer_key="TestMerchant", oauth_nonce="aGDxlipOs21lzMdyp0TGmCltVbBgnaUh", oauth_signature="R6uBD0TnC75UmYVFqEf70YX9tKK7iRmBR%2FoJGPCUTwzzyjtkAg6jK8fk2I0EbzeadqTLDgckrXShSsD5Ke8%2FP3ZqPwWwh3OMT5XK9MWVcDGavjKQi%2BnXfJdr4JRbhPAk1YL3IJL04TTTmAoJHFWu0EKNdzndAMQ0cWay4Hg5evPcDpJEK0a2ZaKnSMjh9UMmttvzDL4Cb2INDH%2F5VadKPji%2FbDAxxWVT%2FQ9HVJcVSDHlxFniLBgyJr4ZIg4ROwtnO3hbOC%2FC5rf7USgjkbpkBUejqjk4Wgw%2BJHMFJ4PJQM0beYn1ctmVGg27MOp8UWyi2i3PsAy8FbPf%2Ff6sMTDhx8MABfbIojHgrvke%2B3flfS%2BUmtCo5pQ%2F9blWvVmB%2BjJz%2BqznYEAUk%2BHj7ekSVzMvpf5LNDeIwpwSVEZpp5Ig8OyKZcWe9i8bbmfDsWehSGpiVkaraWsLCToras3lZy73Hp5z6SN8Uc98f%2BXUF8ROJvSysAfzDU2BJrDhNo1tKjuhY%2FEQzEinYe0zCSsSHOhkl2yU2KwWxbgWXb%2FoMEHIuuZ5l%2Baa%2FGTLSCb%2Bm5wJ8n9QeDSulHM3VmTP%2F7wFXa5DwCQCDy3Lu7vOWVFhLirXOMH6V%2Fe5SZ1yQHo0uH2N7F72DGKrcNkvkLaZCB4NE8AVqISxB484AB5Mo0pC3iZzAPWNo141iezgrlacarwSNsqSwmGBfvCWAkxszqIHgWWOfsomfG4OJTo%2BRgtO6SkLAgpPcGDYWjziDvT6uQvAQG3R5aSv6OgrjZNn0PQqsWb4qT7nlirHLwXXrSL46HTRyCl9q4QCuufKPZA0LOW3y7OJsk2T%2BuI%2FZHXzDOeHGIhxBWa%2B%2BrpYhwDzmx1736gnNZ6dBbzKz5hH20BWOzvaZ93mKDH32Ri62D4yvAf64ElvSdNSImImLtEstRcws9YBsdcAxJw0TXICclwN8DM39jhU7ekc2XsYhmCeEk5f1OL6a0Ud6IyxZN0HLhOPRHHSiiMh90y1DOyk%2FUSjihshg2NDmFJe4TNZ7TZRzlD5WKR6FxeTH6xYq1RJvoHiC0SUyVKjX7knFp%2FIEx3fdpMRD8ZCT%2FgUw5Cu34q87B7xVLHjEhn9%2FV3lacVDJ48F1aS6urv%2FI2cahSsIz288g1V1ThhrusN7TMdIsoZ%2F7XqKxht3p34N0e7lDUVils42ySmZil78GVvr9wR2GtOpa8FT31F0LnyVxCiA3Fqj5LNM3QunElqSaNXI%2BtwlzKFGq4oklwb7bilOin0uzYlb4ymz7x6o7O8dJmCeUpkfCUxFrQnpmmHGBg0VgcKS5S769otXsXICqMP%2BDU2x5dajQvbIlzzm4aKF4qm2jxSowydOWU1Y28Q%3D%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1661493794", oauth_version="1.0"
Content-Length: 305
Content-Type: application/x-www-form-urlencoded
Connection: close
amount=10.42
&card_printed_name=John%20Doe
&client_orderid=1
&credit_card_number=4332435659564446
¤cy=USD
&cvv2=123
&deposit2card=false
&destination-card-no=4998406231653309
&expire_month=12
&expire_year=2099
&ipaddress=1.1.1.1
&order_desc=Your%20order%20description
&redirect_url=http%3A%2F%2Fwww.example.com
&server_callback_url=https://httpstat.us/200
```
**Success Response Example**
```http
HTTP/1.1 200 OK
Server: server
Date: Fri, 26 Aug 2022 06:07:43 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 137
type=async-response
&serial-number=00000000-0000-0000-0000-000002ddaf96
&merchant-order-id=1
&paynet-order-id=6863038
&end-point-id=39509
```
**Fail Response Example**
```http
HTTP/1.1 500 Internal Server Error
Server: server
Date: Fri, 14 Oct 2022 09:53:35 GMT
Content-Length: 61
Connection: close
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Internal server error [1ee76b38-3764-407e-9dfb-2ffc9ab0775b]
```
##### Transfer from PAN to RPI
**Request Example**
```http
POST /paynet/api/v4/transfer/39509 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth oauth_consumer_key="TestMerchant", oauth_nonce="yL2jqiO6NnIVBGhT3ocsWDgsaYxG3P7j", oauth_signature="U5FwR96T0huNFmDQYivbEkLFISfZKF%2FREN%2BwBXLNAD8K0HAAXh0FbmXDSkgvsZXb4i1UPc1xFmqvIX2lYsiZRixMesiRIbAhoHsmHHpGfZ5hS2YMfVAUQWfVbHdqCJQZEJofu7RM1ow8rS0YbGCYvqSHUbI0bDi%2FpXERzDrr5N76AOhl2onBPjqXQqhAdVYBfTUHhezDJChhyg4Lc4gkRsVbw8tIbx220vCT57t9CQhYvNd9bONH6Vkn6XyUVY3bfi%2BNt4CQ25W2F%2FpYVK2%2BtLeCVDHytY7JGaUalWKXg2HIhr2Olmh9GRSZ51tenAL%2FgkHI%2BDsIh5nn6nsBAMFnSCQR7ANy7cUpLw5KZnQLKLFcCeNeBdFqXDwZ2aOX1PDdHvn1KZBtf1SqGp3kkEX3AMin%2F3QTOHobLRFAwGBIExwGxOddRL2mPIOUMvF6CE%2FGgBGHstcjyDCAQ3U2n%2BXlaM1cCgWtLL2A5nBM2%2FMnCUqqYUY4eN2Gidh2ZoLw70v%2BL4jLnK3%2BKefRxyPgOlZQBxH1qfP3tayZlMIdJ8gAdAmx2RlK%2B3krUsy4TSpCzyAX4xloovGgC9yP0u0u4jJT6DTSdTJ3IdiCoUTyAA%2BPdkRrMZ%2BswFRH%2FCU8HETuOGQHUCnbL10DjHCvvis3OtNH6j1aNETfWJqJ29lSngs8%2BU0Q%2FlAGdlRXdAVkqj5Vd5wfLeMvSgjmhPbS6Cfk60hXS%2Bj58DPdlKZ8Itg7gZO%2BW%2BGNfpwkD2baTdAiMjU%2F0ZGx9UW9caT1QrsXL6ub4NXQHnHluCqHH%2Fi6zNOu2pAuHcuJ%2BOLOzcPSDRCFeOk2zy2SAiWKTKWEFypMg2AQuRydrB9ZFPnmVokPnN4Y99ZSdj1PD3VOuXCW1h7AjGub8oMYCaqOvcB8bdSg%2BJYnkWS5CMsQSMjuW5ZhRCtGYlrpq3luQS25h5LLXi3OrqkiQdst0I9lTmmzwQ0OiFmXPcH7nKE8gantsa5hs7BVgPeypY%2BKfVZiqs9w6y2aq%2F9CUtatVj9%2BU56%2FucDhs2b9s6kY3kbvO3p568hlJHvNxgyhv0eGfMSyWjmil3OuZf0VsNlbptGC69nIlXKXgV7sX3B049gN%2Biw08EP8tfpZPE%2BFViY8ecDrs2CquzJpZvOFX4WZ2bbIr9%2BOOcVMhGJ7QrFC96ddnbhfGaDJsc2FCgjBNQJvZJ8Mhxa7kksHujdxFrBa%2BKGSs0qROwTcpxRtb4zBDEcq%2FHklBkB0T6lOWpYvkhUy1coF8KtuhPSfqhkVg6gB5%2B%2BLgGK6DQKIoMI9MvzSLTOR9ElE9vWUUMP1eG2b46jqOiIuAwQvJZfnxqlizF5OcqBbJazBj7t%2FiH0KKPvO6Q%3D%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1661494949", oauth_version="1.0"
Content-Length: 303
Content-Type: application/x-www-form-urlencoded
Connection: close
amount=10.42
&card_printed_name=John%20Doe
&destination_card_recurring_payment_id=1491828
&client_orderid=1
¤cy=USD
&cvv2=123
&deposit2card=false
&credit_card_number=4998406231653309
&expire_month=12
&expire_year=2099
&ipaddress=1.1.1.1
&order_desc=Your%20order%20description
&redirect_url=http%3A%2F%2Fwww.example.com
&server_callback_url=https://httpstat.us/200
```
**Success Response Example**
```http
HTTP/1.1 200 OK
Server: server
Date: Fri, 26 Aug 2022 06:22:43 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 137
type=async-response
&serial-number=00000000-0000-0000-0000-000002ddafb1
&merchant-order-id=1
&paynet-order-id=6863042
&end-point-id=39509
```
**Fail Response Example**
```http
HTTP/1.1 500 Internal Server Error
Server: server
Date: Fri, 14 Oct 2022 12:30:15 GMT
Content-Length: 61
Connection: close
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Internal server error [18819567-ab17-4342-86eb-f8a45966e8c8]
```
##### Transfer from RPI to PAN
**Request Example**
```http
POST /paynet/api/v4/transfer/39509 HTTP/1.1
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth oauth_consumer_key="TestMerchant", oauth_nonce="J5wfdvnj45sDN2TElY2nIHcpDgIPsEa5", oauth_signature="VhvXrMZNTrRxBCd7AOtRWcqc67KLyD6wQpJoVuJP0I4%2BWseXd5bAfMZtuy1QBhVGMlGiVfl97tmiB1LzSTnWcA%2BlS8bCyEXgoE0XL4rn3U2rXV2JWgPTrv1EHCaAt%2FJhZ1JPd6kjzGG3ZDJXAZg3YMoRdL00iK66Z1AK%2BhuL1M9mziEkcvZZR3elREmz%2F223aVXRr%2BXc6dWFTHQM9BDTsVarsHrYHv9TkBjDbYXp%2F%2BX9ltfdUV7YXGemd6jy25CbJC9zbTj1wHsrpT2bkbBCpycH8xtANFAeQgyTpR4IU4OglzPSunXeZaO9o1%2FwzWEvDmHN4g0WRnyl%2Bmgy7qU3wvMyyDf27UCRXFgEmfybk%2Fa3bwouJUqQbYUMif%2FGULsPmdSmz%2FWhmPnyIq9lvNkExE4xIXB1j7C8aYGoSRavvdhmEcNIbyXEs6hur%2FmXkIJH5RHDJTAcfu7RHkRUd3jBQjEEI1q9HnhTmdHKOEovQs%2BzR3K7Fv6%2FLW71cmbMMpqYbkIaBVN0%2Fdx4jLwZwqbk3B6PxxAyf6f48vJDFoNqVrlpaGXWTwZaeLWlE0sCgk3Cscss64%2B%2Bt8eHaVRS2u09uwvlh9iCSqXeZjikHB782u7xc6f8PWp70xK0DsBsN1QyN1%2FLMH1ozr1HsYvZrucC8C7T2BykksEKmitpZ0cRUsj7Hb59nh39xk%2B8Vk1VenfUyz7O%2FnMsOeuKna0RHLI35DqgnvPp0yjU2SqM32N6%2B7Dtaa135N7oC1z8hG1zCB2C%2F%2Bk9Bmt0y%2Fad6yiEMN%2F%2FslGob7U5x82Sf7ph92EFCPu1ccW%2FMbxb9xu8csaMHDbh7E%2FydQm3WOym0U3%2FPSckea23YOTScrr0mQsGOjBwzgehUsJyCyLiWehFob6aEfuphXfdiyb5vXUKZuTAWPofgusJByrOHErhfPgQoUJ96YXfGGFTZAlLP8G5T14ZM02JrWffGGuvDzZiwkK8s9%2FPfZxTCQxjmM%2FIOOkSY48PTjYVq36V7x2v%2FDzJeux1Txu4TpewUod1ZDhxzu8kUEgKgxtJalPcFuZL8dwTynb4LCoKEK8mM15MRXWpHJzJ4k9yH1Rrn8bfEcQWUI5bdgsEdgWRBNMevwRGb3E%2B2ZMO5XihaKA1eCxBtKtxIvNShKjqS5fYdUfRHf5yVRwE67EZx9zAj1lHvTPSB1q1foWbU5MhN9vNc36hkLLsCjiKZsRctGFZGwTrgb6sPMrPoqpj8h66RosFHvi116G2sWe4jlz7OhC2%2BYD%2BQsMiiEIPmlHLWf2Z1w8g7NK%2BigKPI13hyLeOavPDEzV1ngy1XqkIdQdLS1mxxpD8sw9%2F0h4iN7kDgRC3eSwM97%2BO%2FdaN0d14JQ%3D%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1661496079", oauth_version="1.0"
Content-Length: 314
Content-Type: application/x-www-form-urlencoded
Connection: close
amount=10.42
&client_orderid=1
&destination-card-no=4998406231653309
¤cy=USD
&cvv2=123
&deposit2card=false
&card_recurring_payment_id=1491828
&ipaddress=1.1.1.1
&order_desc=Your%20order%20description
&redirect_url=http%3A%2F%2Fwww.example.com
&server_callback_url=https://httpstat.us/200
```
**Success Response Example**
```http
HTTP/1.1 200 OK
Server: server
Date: Fri, 26 Aug 2022 06:41:34 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 137
type=async-response
&serial-number=00000000-0000-0000-0000-000002ddafb6
&merchant-order-id=1
&paynet-order-id=6863043
&end-point-id=39509
```
**Fail Response Example**
```http
HTTP/1.1 500 Internal Server Error
Server: server
Date: Fri, 14 Oct 2022 12:34:35 GMT
Content-Length: 61
Connection: close
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Internal server error [ea7cab67-2af5-408a-aa76-79bba38688cf]
```
##### Transfer from RPI to RPI
**Request Example**
```http
POST /paynet/api/v4/transfer/39509 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth oauth_consumer_key="TestMerchant", oauth_nonce="AC4qZJfR4OZW8xiNX9SrWj5upjPZ74kU", oauth_signature="mF%2BUTmlP7hbIMlfHCbuxDiq%2F3nx6l04zuWZpkVdnw03OHiyNBGdEg2rIsg1SZAg3Eu8VUXGBePyK0wksnyIgcyTigP5apTLrz%2FgpE4o%2BHtP%2FfJ%2B04qQ4fV5WH0RqPjd9xBEaD2JO%2Foe6xYg3tx4u1QZ1MyrQjcJTrpbn%2BOxnia8%2FFruu4Crs3KHLmiUBSSVc9T9YlDu%2BuZfDBCxSqHs1j3T4JoCskfH8VHJ%2FI8igkh5e9qUYD4MrVunhsbcv8KHS0N%2Fb1f5b%2FcoH0QK9ERX7Smo7Ns9ErvbGjJtu%2BwFMffH8%2B4EExtzJbRKQRMYdnY6PxNiu66wzGuMVKCRdTvwc%2FisUnJ0LssFRwnFLamxrytoPj2I45rPkh08ydA2jYCAErR8FYAmk%2BiLrY9pLkAL21BgKLHw%2BJgxUeQAIqLwwHIaNA8AnzP9nvYGu9gRVYfei%2FZ%2Bue%2BqcXBAlDJIGYB0JTGHTEf8t2lOpiI0AEIM%2Fd%2FKF5%2BbPp52Xdde6aKV1FT2A5i8%2FCJEKxuh%2FMWwcSqa88T7m4swnzH879cnkqbgzmSl2PS49poiccDaUwC78ZCxwGVD73FUSsgBnO68kZVpYwBIat543EH1HCvG1sH1xV8Fp8uSBxnjahDGKmi67viQQPlvl5avULcqj9PylSHp%2B%2BMn3L1PPss2G2qai5ITLunNfyFXzofotvR7KrprM3EuZmB47eanQ0nxmpyvBI2BsvObO8bJ97EPSxjhIyjdYoTq8F2GEumMsqZCj6tHZFO9%2Fd7iSJvjfxHLa%2FIQjew%2BguK%2BTL%2Bw1lPCDq9monQ8EX7OT1kh91DVjlcxglqqxqpWt%2BWCY56ZXuEKZ6kqYjT6N2ab2bjGTiBrcgmToq7gvcbKdMCcqgzPJZR5tK%2Fc%2Fu2hepO2L0%2BU%2FzG9IB55iFoq2c2qG32T%2Bg8K54WGPAyzubkW3mKy9B8VwlzUu%2FWSKNQgtbf2pqVOLUZ%2FTCa1ood9CqfNF%2B2ECo8x1ubyyzbBaUIW86fA1cgXptgmJp6G5xapky877ND9XXBRlXvOS6%2BlcItiqB%2FfQEIs7awflpyRlGQQJttpGrJTqjYXiFbvmlA1Z98l8yZ2aZmDi%2BfxcGkICtnjUYZnlYU%2BO7Eo%2FlV%2BrcbQMQzXp6zYHd7hPTwuNZ0fS%2FGAzd1bfVXkBTszqB8PZuuQEs5ObBfWjGbJGKhY8KuFgcR7B61hamzfhokCMGcxOMJP6YY9ZWqU4ba9WT04ZU53pgEJmUTuRCKtVqVL%2FgT1GlzlKQJN80gZ1Wb9t13yVRva%2FTRn%2FOXzfBhPIrxJv0KfXLUx8qHDweBwo5U2r8CG0N4xW5GJTgs2ncDBNXjWSjLE3dhG9G1louVP3ydryCQ%3D%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1661496711", oauth_version="1.0"
Content-Length: 312
Content-Type: application/x-www-form-urlencoded
Connection: close
amount=10.42
&card_recurring_payment_id=1491830
&client_orderid=1
¤cy=USD
&cvv2=123
&deposit2card=false
&destination_card_recurring_payment_id=1491829
&ipaddress=1.1.1.1
&order_desc=Your%20order%20description
&redirect_url=http%3A%2F%2Fwww.example.com
&server_callback_url=https://httpstat.us/200
```
**Success Response Example**
```http
HTTP/1.1 200 OK
Server: server
Date: Fri, 26 Aug 2022 06:52:10 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 137
type=async-response
&serial-number=00000000-0000-0000-0000-000002ddafbb
&merchant-order-id=1
&paynet-order-id=6863044
&end-point-id=39509
```
**Fail Response Example**
```http
HTTP/1.1 500 Internal Server Error
Server: server
Date: Fri, 14 Oct 2022 12:38:47 GMT
Content-Length: 61
Connection: close
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Internal server error [317a3dcd-a96e-4b3a-801c-c5cfe7d05dad]
```
##### Transfer from Deposit to PAN
**Request Example**
```http
POST /paynet/api/v4/transfer/39509 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth oauth_consumer_key="TestMerchant", oauth_nonce="Fw1O8eTrqovCuHhmHJ35utckB11MkfwD", oauth_signature="DRmRSQPQPw%2BkDcpNiOboL98MDQzvH73OfM%2F0ylUFoUbm165GsbkhT0TJhFD%2BjpSLiEXnzinRaiDtTc%2FoEDLVuCf7EjNfIsKT6xLEkp39xf08yrr2QWeqeAu6mpmwzq7%2BVNVobo0UCzQXMCZbkZOh%2B4US2pbJbZ0QrZFwGo%2Fd73weyecFBe4Z3ua4Q94MvMUKioH%2FD%2FvjFvlB6Mf8ua6b3%2Fmo5%2BiRwXykic1mWUBf7TB6MXgpRcu9eET3BbGc8%2FS0Xn9Lv2KE%2FoUYN4SmE%2BWgZXE3WR5DALkVrKYzXO5pOguqsy3IAp%2Blu%2F1XaU%2BxqxclAF%2B4KBGlrQt2RINSe%2FgCHTh9qwTiNJcCURdVZ%2Bid6jqGWo4IswEwRgCAHvOXbsoZTj2qW6YqpCm7U1v58FSbLhMlQy%2Fp6cpArnLGU1KDRjVo4nzFnsgIJaPw1im2PuM13X1ueaPsb7wEPWdJbpzs5cLViI7pkPSXSVWCApRsCRu%2B25%2FzSqrz%2FPwO4%2F3dhbkP9CDw9BMOAtonBJzHJtFDKsM2x0U56qv1xaJgEYGUVaOwyy%2FZnOrde4kPX2tkaBF6fFzZkoaMLI1CqBWbQHvWTXZ1vgWe6NIQmFve9NPjA69%2FEhTO2SREA8R2GkSOhF1UBtc1cRg8z6dY4jXbqr7UfwSsu%2BI3JB7%2BDTlMEOVSpfTEA8pbuqHwQL9YGV2BYPUTkVTMIfuetz2byaNafv9TsdV1QBi5uqbjT%2FTXeZ3214zL7rIU1UpqAHXkAcEraZDQV3h5X0i37yTmCOvMkfBl%2B0DnhZbSHkgCLd5aqDc4Hm0pvTfDFa92PcqAqOrK4TMERKQUkjMJFucoWP3fjRS7dQFsBLpWTbtKoNkycALHtd%2BI0PIzglrpJoO9AoHMbQJGZd4OXouBnkjo0KjjJqP4ZRGdtfMH4ADSj%2FyC1w0OaWcZGNkNEABS%2BRVpGD9VCOrYoe695Xt9XV4UEGygCReJ92WqhbnqafrGVu6eXCeIuV7KaUH7aLps5YzIySpDeJLKQTU5J7TuCZfOniLh5C2to%2Bl0h0BnqHX5FsU6RzQnPF9QkU0i1A2K%2B1nfqYOHUFq8wJNo4BIQwosUo7FzYRVzgSXqMnF5gQ7NYMkwxCaUz96XNTDj1vlzQWSyo3AgS6Jb5oIy5yr%2B%2FJPdzEcHf37Ot7kUAtmE3fLZrH%2BcrUd2jZ7tRHxcndQiTodbT0pjhT2qv4WcbXqPaWIWURBB8OxdH7QELxPyG%2BUUvPaiUGscDZ76aJnEk%2BT5jBC2Hak8%2B9Zy4qB%2Ft2QCTPwoAkuC2oHUafzaA8JzytjJLVQpTFvLh7Lj%2BAWg7KZGqKfYX1tmDsYUrdBRb9PfgmCPZ6owEkbDPQ%3D%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1662384499", oauth_version="1.0"
Content-Length: 197
Content-Type: application/x-www-form-urlencoded
Connection: close
amount=10.42
&client_orderid=1
¤cy=USD
&deposit2card=true
&destination-card-no=4402746838361941
&ipaddress=1.1.1.1
&order_desc=Your%20order%20description
&server_callback_url=https://httpstat.us/200
```
**Success Response Example**
```http
HTTP/1.1 200 OK
Server: server
Date: Mon, 05 Sep 2022 13:28:35 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 137
type=async-response
&serial-number=00000000-0000-0000-0000-000002ddb02e
&merchant-order-id=1
&paynet-order-id=6863078
&end-point-id=39509
```
**Fail Response Example**
```http
HTTP/1.1 500 Internal Server Error
Server: server
Date: Fri, 14 Oct 2022 12:58:56 GMT
Content-Length: 61
Connection: close
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Internal server error [3fc83866-7aac-4c92-b6e9-828069e5a9d2]
```
##### Transfer from Deposit to RPI
**Request Example**
```http
POST /paynet/api/v4/transfer/39509 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth oauth_consumer_key="TestMerchant", oauth_nonce="F2ab2fvpltW1oWmn7xV1coohcnHXAROc", oauth_signature="V5ufFoDRY%2BMR8pUP6PgCOHg2M8t53EepdzSvqzzMdQVQ3oEoyPW0TPQK1daviExQ%2FF%2Ft1Lc77n1RKopD0SXbM2UBXe%2FE9RNDERHO4blb01bKCTm9N2IAUTW5PWKcreOLYuiCt2nh5cwY2hFbvxFl5EPoUk06AIoA9wFmrNEICBQJtDhtj7bULmAZhqoXgifgPEcNsfsNDZlk4mQLRhjsONbehon7GlsU8u0itV9I0S0qZnld4zfX5UOORi3xpMEnUfn4DVuLEgElIGeOJ1Th8r3LuO53QYOcmpyJ28Es%2FXDLZh0%2Fg2jJ8kaamcL3EMewZcIwyB1FOiKUBniwX%2BXattNeXbniXTBqPG%2B653RpqEMG3YwAIbAobxLk%2B2q6plW5EDApY8rXXv61WBzVJ2pfBakWHUGslBl5SynzzhE14EFDT6eL4dl22qm%2FM6i7fJGea2d5zFboVgZ0uIXChOgtoN8gJa3mMHt2isfRzuCg8K22hkgNy3CMYeUh7TFYxgsAr14pBXKjMS6MgMvXnPsxWoMlTF4dE9xQRY7nS42K%2FcrECPfnIcjK8HvT%2Bsux4ytps%2BKrBBfXnq%2Bjg%2BtT7LjR1mQnvaWw5HRMDlz1C%2BsmO4J%2BLJQBmpKknFNBv3oxGejhzZTtVcEGddCMNeh4KXUCMucJdb1I8ssq03yFS%2FPrDZbbdK%2Fy7VonLxWg0jozw6l46M9YLvJE9clUBvhgpuG6ClMecpgoQvDMnR%2BIx3zl1qy6E8eDyaXJ%2Bh4opohJrSRGDiTcVtGRbcZUr%2FWyLDUR625LjavHv9zT1aGGieSTsNM%2BeLgxkSzRlyXR4E4zjqDAB3J9rwKKbZyx8gTduMhGydUGDapNwKVhC5hb0F%2ByYjwiz2MO5Qr40mdeBfejdAJx4%2ButBszx0lOuczlIjR8L8NAn5LVrmuf33nLT63J8mTgXU%2F1bnQQHvmnTA4nX2NkpXbUDHfry8H%2FOoyCbs6dChX4RrJOQkS49tjxzJuiFIxAsUHkrlxdS9cHuluG5%2FV%2Fp6IwYHcWhUG2PxW6PJAcuin32sM66p%2Ff63CAcu46V9cIyoXpeSBvYZMZ8jt6Guowy5uHDImUFli%2FHCVopWLs%2FRFyY2iJUmqKypGh7Po%2FJyVhAYdpXrpaLTEmOd4OpLUO0GaxjaPTmcKuDGmXDQEFmC00zAT6%2F57tvZ38bhqSbReM5dWZC6mog9iC2wjY4gpDf%2FUTX7gPGmQkefTysz84QdRdoDNi0BDDfBD5lOPSpZmMs67obwXgnsrJOdlGNRyEjQ%2B8hZgxXH2mWh2wX4skHq43kxaJJ2bdIVab9BNtVj5YjnUJxJWJoe0a0%2B7slFQwfxIm8lxKwtJdEgK6r01UOLg%3D%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1662384669", oauth_version="1.0"
Content-Length: 206
Content-Type: application/x-www-form-urlencoded
Connection: close
amount=10.42
&client_orderid=1
¤cy=USD
&deposit2card=true
&destination_card_recurring_payment_id=1491830
&ipaddress=1.1.1.1
&order_desc=Your%20order%20description
&server_callback_url=https://httpstat.us/200
```
**Success Response Example**
```http
HTTP/1.1 200 OK
Server: server
Date: Mon, 05 Sep 2022 13:31:42 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 137
type=async-response
&serial-number=00000000-0000-0000-0000-000002ddb02f
&merchant-order-id=1
&paynet-order-id=6863079
&end-point-id=39509
```
**Fail Response Example**
```http
HTTP/1.1 500 Internal Server Error
Server: server
Date: Fri, 14 Oct 2022 12:55:09 GMT
Content-Length: 61
Connection: close
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Internal server error [51a48bc5-a061-40c5-b88b-f2c084024b77]
```
#### Open API Collection
Open this method in the OpenAPI Reference
View in OpenAPI
### /api/v4/update-recurring-payment
#### Introduction
/api/v4/update-recurring-payment is a synchronous API command. If request is accepted with no errors, the Payment Gateway finds the recurring payment profile by the provided recurring-payment-id and updates this profile. The recurring transactions will be processed according to the updated recurring payment profile using the payment data saved in this profile.
Update recurring payment is initiated through HTTPS POST request by using [URLs](#api-v4-update-recurring-payment-request-url) and the [parameters](#api-v4-update-recurring-payment-request-parameters) specified below. Use [OAuth RSA-SHA256](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md) for authentication.
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|---------------------------------------------------------------------------------|------------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v4/update-recurring-payment/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v4/update-recurring-payment/ENDPOINTID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded and [Authorization headers](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md).
> **Note:** The RPI details screen (recurring payment profile) contains information about linked cardholder and customer data, recurring schedule and processed transactions with this RPI. This screen also contains change history for this RPI. The change history is currently available for source cards (SRC) only.
Type native on UI means that The recurring payment setup and the actual charges are in the same acquirer.
If the recurrent has switched to Stopped, you can update its schedule using the start-date and finish-date parameters. However, it can only be resumed via the UI by clicking on Resume.
To stop the automatic recurring schedule, use [Request Parameters](#api-v4-update-recurring-payment-request-parameters). Available only for SRC.
| Parameter Name | Description | Value |
|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------|
| client-orderid | Connecting Party order ID. | `Necessity`: Required `Type`: String `Length`: 128 |
| recurring-payment-id | Recurring ID assigned to the order by QA. | `Necessity`: Required `Type`: String `Length`: 128 |
| credit-card-number | Payer’s credit card number. card-printed-name can only be specified when card number is specified. | `Necessity`: Conditional `Type`: Numeric `Length`: 19 |
| card-printed-name | Payer\`s card printed name. Required when card number is specified. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| expire-year | Payer\`s card expire year. Can only be specified when card number is specified. Required when card number is specified. | `Necessity`: Conditional `Type`: Numeric `Length`: 4 |
| expire-month | Payer\`s card expire month. Can only be specified when card number is specified. Required when card number is specified. | `Necessity`: Conditional `Type`: Numeric `Length`: 2 |
| amount | Amount of currency must be the same as currency on the project assigned. Upon reaching finish date, Recurring payment will go into stop status. Supported for SRC and DST type. Required if amount-from and amount-to or amount-sequence are not used. | `Necessity`: Conditional `Type`: Numeric `Length`: 10 |
| amount-from | If the combination of amount-from and amount-to is chosen, every charge will be of random amount between these two numbers. Supported for SRC and DST type. Required if amount or amount-sequence are not used. | `Necessity`: Conditional `Type`: Numeric `Length`: 10 |
| amount-to | If the combination of amount-from and amount-to is chosen, every charge will be of random amount between these two numbers. Supported for SRC and DST type. Required if amount or amount-sequence are not used. | `Necessity`: Conditional `Type`: Numeric `Length`: 10 |
| amount-sequence | If amount sequence is chosen, client will be charged amounts from this list. Example of setting up amount sequence: 10.5, 24.6, 32.0. If repeats number is higher than amount sequence number of elements, every new charge will be with last amount in amount sequence. In order for charges to begin from the first amount in the chain, current repeats number must be set as 0. Supported for SRC and DST type. Required if amount-from and amount-to or amount are not used. | `Necessity`: Conditional `Type`: Numeric `Length`: 10 |
| period | Possible values are: day, week and month. In case if daily is chosen, client will be charged every day. If week - every 7 days. If monthly is chosen, client will be charged on the same date of the month, from the starting date, no matter how many days there are in a month. Interval and period can only be specified or omitted together. Not supported for DST. | `Necessity`: Conditional `Type`: String `Length`: 32 |
| interval | Interval is a multiplier applied to the period. For example, if interval of 2 and period ‘Daily’ is selected, client will be charged once every 2 days. Interval and period can only be specified or omitted together. Not supported for DST. | `Necessity`: Conditional `Type`: Int `Length`: - |
| customer-ip | Payer\`s IP address. Supported for SRC and DST type. | `Necessity`: Optional `Type`: String `Length`: 45 |
| country | Payer\`s country. | `Necessity`: Optional `Type`: String `Length`: 2 |
| city | Payer\`s city. | `Necessity`: Optional `Type`: String `Length`: 128 |
| address1 | Payer\`s address. | `Necessity`: Optional `Type`: String `Length`: 256 |
| first-name | Payer\`s first-name. | `Necessity`: Optional `Type`: String `Length`: 128 |
| last-name | Payer\`s last-name. | `Necessity`: Optional `Type`: String `Length`: 128 |
| order_desc | Description of Recurring payment. | `Necessity`: Optional `Type`: String `Length`: 65K |
| zip-code | Payer\`s zip-code. | `Necessity`: Optional `Type`: String `Length`: 10 |
| birthday | Payer\`s birthday date. | `Necessity`: Optional `Type`: 8/Numeric, DD.MM.YYYY `Length`: 8 |
| email | Payer\`s email. | `Necessity`: Optional `Type`: String `Length`: 128 |
| ssn | Social security number field. | `Necessity`: Optional `Type`: String `Length`: 32 |
| phone | Payer’s full international phone number, including country code. Not supported for DST. | `Necessity`: Optional `Type`: String `Length`: 128 |
| state | Payer’s state. Please see [Mandatory State codes](https://doc.payneteasy.com/integration/reference/country_codes.html.md) for a list of valid state codes. Required for USA, Canada and Australia. Not supported for DST. | `Necessity`: Optional `Type`: String `Length`: 2-3 |
| start-date | Date, when first charge is scheduled. If start date is set as a current date and type is set as auto, first charge will be made today. | `Necessity`: Optional `Type`: 8/Numeric, DD.MM.YYYY `Length`: 8 |
| finish-date | Date, when the Payer will be charged last time. | `Necessity`: Optional `Type`: 8/Numeric, DD.MM.YYYY `Length`: 8 |
| max-repeats-number | Index of recurring transaction, first charge will hold the index of 0. Current repeats number increases even if a charge was unsuccessful. When current repeats number reaches max repeats number, Recurring payment goes into stop status and client is charged no more. If a charge was made automatically, no additional charges will be made (unless done manually), even if a recurring payment is stopped and rescheduled again. | `Necessity`: Optional `Type`: Int `Length`: - |
| purpose | Purpose of transaction. | `Necessity`: Optional `Type`: String `Length`: 128 |
| notify_url | Notify url field. server_callback_url parameter can also be used. For more information please see [Connecting Party Callbacks](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). | `Necessity`: Optional `Type`: String `Length`: 1024 |
| server_callback_url | Connecting Party URL which will receive callback request once the transaction reaches final status. Connecting Party may use Server Callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. See callback details in [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). Send either notify_url or server_callback_url, not both. | `Necessity`: Optional `Type`: String `Length`: 128 |
#### Response Parameters
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
> **Warning:** /api/v4/create-recurring-payment is a synchronous API command. The response will be returned after the recurring payment profile will be created on Payment Gateway side.
| Response Parameters | Description |
|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. Example: update-recurring-payment-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details. |
| status | If request is accepted, this parameter has approved value. This is not a transaction status. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
| error-message | If status is declined or error this parameter contains the reason for decline or error details. |
| error-code | The error code in case of declined or error status. |
#### Request Example
```http
POST /paynet/api/v4/update-recurring-payment/ HTTP/1.1
User-Agent: curl/8.4.0
Accept: */*
Authorization: OAuth oauth_consumer_key="ErwinTestMerchant", oauth_nonce="XBhUVJU4N8fBnNRGfY91Z3wuZ6iNgjVM", oauth_signature="RIRufAZeoBZBMpVlr7Bt%2Bc6fDTUxZJgxjJUlTo7Pm9zlGeZAl427VF6c%2B0lkGvZfATlooYBK%2FeoZaUU5gJITePycMmZr2gPzAk8xCielclB8N0j5Rp3ga0A%2B3uJDTgQdvsrosYK4tsES%2BPsR6qjhf%2FqWGHbpwCooXbMLwI9a9yMdkwmcRNQGPWAz7I%2FJ8gdDLvkjM0H8fZRp%2Bz%2FSAd3%2FgX%2F%2BCJv7bMn26hOGUxJua7u5GIKX6mmZ5FpV71xdy04ebPu4qAXGPGNKBZXLJGqzYfYVlW9XWKKkFhUA4RLYUZqnfokHA8uy3zb8IY8tKZOjXxmytlFKdVr%2BYAiHxlMt%2BEq%2BlovLAXWENbIXvJYhRiX%2F3QO2cq2ZznAsanZQiyU7AT3O9lnLHuvKc2wbuFKr277lNR24cykI3ja%2FGMR%2F8T%2BXjZKFF%2F1sYVRGd93CQDx6NHnH98vp%2Bv3PMopOmLWwggyOApmDBDsa8jYoU1TDOs6gNRTsXIyFiSwl3e48fNAp%2FjFZfUl90K8wGusNzrof05UdTPR%2B7zpv4jL1hd1XyN%2F4x7aNNQ28tm5LSoVU6t%2BQkvwRm%2FNxnDKMYEE9rq7s4Uq5KTzAmM89pAu52WFbDQXYoZgy3vm%2B0SsJDXH0IVXsDpLDt1zcJClWoeXxT0fqOcEojJhuosvbcI%2FIaEpxWH8%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1721312815", oauth_version="1.0"
Content-Length: 624
Content-Type: application/x-www-form-urlencoded
Connection: keep-alive
address1=1234%20Peace%20street
&amount=55
&birthday=1980-01-02
&card-printed-name=JOHN%20SMITH
&recurring-payment-id=1492124
&city=Chicago
&client-orderid=1575634981130
&country=US
&credit-card-number=4464920026265488
¤cy=USD
&customer-ip=1.2.3.4
&email=john.smith%40example.com
&expire-month=12
&expire-year=2040
&finish-date=2040-01-01
&first-name=John
&interval=1
&last-name=Smith
&max-repeats-number=1000
¬ify-url=http%3A%2F%2Fexample.com%2Fnotify-me
&order_desc=testing%20purposes
&period=week
&phone=12345678
&purpose=No%20purpose%20at%20all
&ssn=1234
&start-date=2030-01-01
&state=IL
&zip-code=123456
&server_callback_url=https://httpstat.us/200
```
#### Success Response Example
```http
HTTP/1.1 200
Server: server
Date: Thu, 18 Jul 2024 14:27:39 GMT
Content-Type: text/html;charset=utf-8
Connection: keep-alive
Keep-Alive: timeout=60
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 107
type=update-recurring-payment-response
&serial-number=00000000-0000-0000-0000-000002f36d82
&status=approved
```
#### Fail Response Example
```http
HTTP/1.1 500
Server: server
Date: Thu, 18 Jul 2024 14:41:27 GMT
Content-Length: 61
Connection: keep-alive
Keep-Alive: timeout=60
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Internal server error [00b20f25-2933-48e3-973b-0664114b8492]
```
#### Open API Collection
Open this method in the OpenAPI Reference
View in OpenAPI
### /api/v4/update-recurring-payments
#### Introduction
If request is accepted with no errors, the Payment Gateway finds the recurring payment profile for each provided recurring-payment-id and updates these profiles. The recurring transactions will be processed according to the updated recurring payment profiles using the payment data saved in each profile.
Update recurring payment Multiple is initiated through HTTPS POST request by using [URLs](#api-v4-update-recurring-payments-request-url) and the [parameters](#api-v4-update-recurring-payments-request-parameters) specified below. Use [OAuth RSA-SHA256](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md) for authentication.
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|----------------------------------------------------------------------------------|-------------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v4/update-recurring-payments/ENDPOINTID | https://gate.payneteasy.eu/paynet/api/v4/update-recurring-payments/ENDPOINTID |
#### Request Parameters
> **Note:** Request must have content-type=application/x-www-form-urlencoded and [Authorization headers](https://doc.payneteasy.com/integration/general_api_usage/request_authentication_methods/oauth.html.md).
Below is a description of each parameter that can be included in the CSV and added to payload parameter which will be used in the request.
Any changes to recurring payment profile made with Update command can be viewed only via UI.
> **Note:** The RPI details screen (recurring payment profile) contains information about linked cardholder and customer data, recurring schedule and processed transactions with this RPI. This screen also contains change history for this RPI. The change history is currently available for source cards (SRC) only.
Type native on UI means that The recurring payment setup and the actual charges are in the same acquirer.
If the recurrent has switched to Stopped, you can update its schedule using the start-date and finish-date parameters. However, it can only be resumed via the UI by clicking on Resume.
To stop the automatic recurring schedule, use finish-date in the past in [Request Parameters](#api-v4-update-recurring-payments-request-parameters).
| CSV Parameter Name | Description | Value |
|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------|
| client-orderid | Connecting Party order ID. | `Necessity`: Required `Type`: String `Length`: 128 |
| recurring-payment-id | Recurring ID assigned to the order by QA. | `Necessity`: Required `Type`: String `Length`: 128 |
| credit-card-number | Payer\`s credit card number. | `Necessity`: Required `Type`: Numeric `Length`: 19 |
| card-printed-name | Payer\`s card printed name. | `Necessity`: Required `Type`: String `Length`: 128 |
| expire-year | Payer\`s card expire year. | `Necessity`: Required `Type`: Numeric `Length`: 4 |
| expire-month | Payer\`s card expire month. | `Necessity`: Required `Type`: Numeric `Length`: 2 |
| amount | Amount of currency must be the same as currency on the project assigned. Upon reaching finish date, Recurring payment will go into stop status. Supported for SRC and DST type. Required if amount-from and amount-to or amount-sequence are not used. | `Necessity`: Conditional `Type`: Numeric `Length`: 10 |
| amount-from | If the combination of amount-from and amount-to is chosen, every charge will be of random amount between these two numbers. Supported for SRC and DST type. Required if amount or amount-sequence are not used. | `Necessity`: Conditional `Type`: Numeric `Length`: 10 |
| amount-to | If the combination of amount-from and amount-to is chosen, every charge will be of random amount between these two numbers. Supported for SRC and DST type. Required if amount or amount-sequence are not used. | `Necessity`: Conditional `Type`: Numeric `Length`: 10 |
| amount-sequence | If amount sequence is chosen, client will be charged amounts from this list. Example of setting up amount sequence: 10.5, 24.6, 32.0. If repeats number is higher than amount sequence number of elements, every new charge will be with last amount in amount sequence. In order for charges to begin from the first amount in the chain, current repeats number must be set as 0. Supported for SRC and DST type. Required if amount-from and amount-to or amount are not used. | `Necessity`: Conditional `Type`: Numeric `Length`: 10 |
| period | Possible values are: day, week and month. In case if daily is chosen, client will be charged every day. If week - every 7 days. If monthly is chosen, client will be charged on the same date of the month, from the starting date, no matter how many days there are in a month. Interval and period can only be specified or omitted together. Not supported for DST. | `Necessity`: Conditional `Type`: String `Length`: 32 |
| interval | Interval is a multiplier applied to the period. For example, if interval of 2 and period ‘Daily’ is selected, client will be charged once every 2 days. Interval and period can only be specified or omitted together. Not supported for DST. | `Necessity`: Conditional `Type`: Int `Length`: - |
| country | Payer\`s country. | `Necessity`: Optional `Type`: String `Length`: 2 |
| city | Payer\`s city. | `Necessity`: Optional `Type`: String `Length`: 128 |
| address1 | Payer\`s address. | `Necessity`: Optional `Type`: String `Length`: 256 |
| first-name | Payer\`s first-name. | `Necessity`: Optional `Type`: String `Length`: 128 |
| last-name | Payer\`s last-name. | `Necessity`: Optional `Type`: String `Length`: 128 |
| customer-ip | Payer\`s IP address. Supported for SRC and DST type. | `Necessity`: Optional `Type`: String `Length`: 45 |
| order_desc | Description of Recurring payment. | `Necessity`: Optional `Type`: String `Length`: 65K |
| zip-code | Payer\`s zip-code. | `Necessity`: Optional `Type`: String `Length`: 10 |
| birthday | Payer\`s birthday date. | `Necessity`: Optional `Type`: 8/Numeric, DD.MM.YYYY `Length`: 8 |
| email | Payer\`s email. | `Necessity`: Optional `Type`: String `Length`: 128 |
| ssn | Social security number field. | `Necessity`: Optional `Type`: String `Length`: 32 |
| phone | Payer’s full international phone number, including country code. Not supported for DST. | `Necessity`: Optional `Type`: String `Length`: 128 |
| state | Payer’s state. Please see [Mandatory State codes](https://doc.payneteasy.com/integration/reference/country_codes.html.md) for a list of valid state codes. Required for USA, Canada and Australia. Not supported for DST. | `Necessity`: Optional `Type`: String `Length`: 2-3 |
| start-date | Date, when first charge is scheduled. If start date is set as a current date and type is set as auto, first charge will be made today. | `Necessity`: Optional `Type`: 8/Numeric, DD.MM.YYYY `Length`: 8 |
| finish-date | Date, when the Payer will be charged last time. | `Necessity`: Optional `Type`: 8/Numeric, DD.MM.YYYY `Length`: 8 |
| max-repeats-number | Index of recurring transaction, first charge will hold the index of 0. Current repeats number increases even if a charge was unsuccessful. When current repeats number reaches max repeats number, Recurring payment goes into stop status and client is charged no more. If a charge was made automatically, no additional charges will be made (unless done manually), even if a recurring payment is stopped and rescheduled again. | `Necessity`: Optional `Type`: Int `Length`: - |
| purpose | Purpose of transaction. | `Necessity`: Optional `Type`: String `Length`: 128 |
| notify_url | Notify url field. server_callback_url parameter can also be used. For more information please see [Connecting Party Callbacks](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). | `Necessity`: Optional `Type`: String `Length`: 1024 |
| server_callback_url | Connecting Party URL which will receive callback request once the transaction reaches final status. Connecting Party may use Server Callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. See callback details in [Connecting Party callback parameters](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md). Send either notify_url or server_callback_url, not both. | `Necessity`: Optional `Type`: String `Length`: 128 |
#### Response Parameters
> **Note:** Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Response Parameters | Description |
|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | The type of response. Example: update-recurring-payment-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details. Multiple error codes may be received: 200, 403, and 500. For the 500 error code, an additional error ID will be returned. |
| status | See [Status List](https://doc.payneteasy.com/integration/reference/statuses.html.md) for details |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Merchant |
#### Request Example
**Step 1.** Create a CSV with the provided structure:
```http
"client-orderid";"recurring-payment-id";"payment-description";"first-name";"last-name";"address1";"city";"zip-code";
"country";"state";"phone";"email";"customer-ip";"period";"interval";"start-date";"finish-date";"max-repeats-number";"amount";
"amount-from";"amount-to";"amount-sequence";"currency";"card-printed-name";"credit-card-number";"expire-month";"expire-year"
```
**Step 2.** Encode CSV to base64 with the following command:
```bash
base64 update-recurring-payments-example.csv
```
**Step 3**. Assign the base64 encoded value to payload parameter and send the request:
```http
POST /paynet/api/v4/update-recurring-payments/ HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/8.4.0
Accept: */*
Content-Type: application/x-www-form-urlencoded
Authorization: OAuth oauth_consumer_key="ErwinTestMerchant",oauth_signature_method="RSA-SHA256",oauth_timestamp="1727177782",oauth_nonce="Js4dwXkF8eI",oauth_version="1.0",oauth_signature="VwdA7BQ68v%2BmpB0N%2BUOxK%2BxYk355i1QzeUPGGGFwDEBn7Y8v1xpSolGQ45HehGmJHNjXHc7A1mP3x7V7r2pQju1LpDEvAb2MHNLSCHiCEjI95sCtrotE%2Fs5%2FmQmIJ8te%2FGFCR1uK%2BzMPG8bpHqn%2B5EIEsuLPq6TSOjD0N3RvnV%2BHdmjH5cxTcmtRrcY0u6VIpvkBUlqpKuTVJXLvbpxRexvgPMDow78QS3DLRQhi6G7Y%2FVshKpKC%2FSRThhe8L33tFckX6KaEbJ3XIMEmP7O%2F%2FQdLfWQBn4ldSp8K8lpkgZks4CZbAjDY%2BQpSfwdc1s8kJf17Ymk1R69aGBmjzJrw00tV4dzY4DE6XVqSTUR8X%2FCa0XMrtD46ichsFoRvFtIeyV%2FIud%2F%2FLSb8XDqk%2BaftSLazBokmT8Qe1FMf0UMgUYBLCl0B4O66Ys8kH4Z6guC2MXarwu%2BDlfuelrcAHevS68hewrMb%2FjppSJWAbQiBOABeW6s1Rb4dvbJnZribkKhEwrxmnT5drsTYvukC2UCoUblEOgVkFHdHk5E3OqT4wMxqXojlYr5Il7m1GkHVYELb964ukROLkohGoTjYEKj%2FUHirjybDWeynTCSaGe%2Bv3JtEbkydWXannkdtTvk0xkbT6LurBiNWy1FuSTmKod9ibqyNiEv6j%2Be14BBGXs3xc5A%3D"
Content-Length: 888
Connection: keep-alive
payload=cmVjdXJyaW5nLXBheW1lbnQtaWQ7dHlwZTtjbGllbnQtb3JkZXJpZDtwYXltZW50LWRlc2NyaXB0aW9uO2ZpcnN0LW5hbWU7bGFzdC1uYW1lO2FkZHJlc3MxO2NpdHk7emlwLWNvZGU7Y291bnRyeTtzdGF0ZTtwaG9uZTtlbWFpbDtjdXN0b21lci1pcDtwZXJpb2Q7aW50ZXJ2YWw7c3RhcnQtZGF0ZTtmaW5pc2gtZGF0ZTtjdXJyZW50LXJlcGVhdHMtbnVtYmVyO21heC1yZXBlYXRzLW51bWJlcjthbW91bnQ7YW1vdW50LWZyb207YW1vdW50LXRvO2Ftb3VudC1zZXF1ZW5jZTtjdXJyZW5jeTtjYXJkLXByaW50ZWQtbmFtZTtjcmVkaXQtY2FyZC1udW1iZXI7ZXhwaXJlLW1vbnRoO2V4cGlyZS15ZWFyO2N2djI7cHVycG9zZTtub3RpZnktdXJsO3NzbjtiaXJ0aGRheQ0KMTQ5MjI4NjttYW51YWw7MTIzNDU2Nzg5MDtPdXIgc3VwZXIgZ29vZHM7Sm9objtTbWl0aDsxMjM0IFBlYWNlIHN0cmVldDtDaGljYWdvOzEyMzQ1NjtVUztJTDsxMjM0NTY3ODtqb2huLnNtaXRoQGV4YW1wbGUuY29tOzEuMi4zLjQ7d2VlazsxOzAxLjAxLjIwMzA7MDEuMDEuMjA0MDswOzEwMDA7MTA7Ozs7VVNEO0pPSE4gU01JVEg7NDUzODA5NjQxNTA4NDc1NjsxMjsyMDIwOzEyMztObyBwdXJwb3NlIGF0IGFsbDtodHRwOi8vZXhhbXBsZS5jb20vbm90aWZ5LW1lOzEyMzQ7MDIuMDEuMTk4MA0K
```
#### Success Response Example
> **Note:** The successful response has empty body and HTTP code 200.
```http
HTTP/1.1 200
Server: server
Date: Tue, 24 Sep 2024 11:40:45 GMT
Content-Length: 0
Connection: keep-alive
Keep-Alive: timeout=60
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
```
#### Fail Response Example
> **Note:** The unsuccessful response has empty body and HTTP code 403.
```http
HTTP/1.1 403
Server: server
Date: Wed, 25 Sep 2024 08:47:54 GMT
Content-Length: 0
Connection: keep-alive
Keep-Alive: timeout=60
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
```
### Verification card mapping notification
#### Introduction
Verification card mapping notification is initiated through HTTPS POST request by using [URLs](#api-url-verification-card-mapping-notification) and the [parameters](#api-parameters-verification-card-mapping-notification).
Card mapping notification is used to allow Consumer credentials (phone, email, billing address, twitter name, etc) for mapping to card data. Card mappings can be used later in transfer or sale transactions instead of card numbers and other cardholder information. Payneteasy sends Verification card mapping notification request to Connecting Party’s server/proxy with created on its side card reference - {server Card Id}.
Connecting Party’s server maps this {server Card Id} to {client Card Id}, created on its side. This {client Card Id} can then be mapped in Connecting Party’s app or on Connecting Party’s server to any Consumer’s data from the initial Perform validation request. This allows Connecting Party’s app to process sale or transfer transactions by Consumer’s email, phone number, etc.
{unique Reference Card Id} remains the same if Consumer makes another verification with the same card number but different expiry date, for example. It can be used by Connecting Party for loyalty programs or fraud control.
#### API URLs
> **Note:** This is an example of URL format on Connecting Party server.
| Connecting Party Server |
|-------------------------------------------------------------------|
| https://proxy.connectingpartyserver.com/verification/notification |
#### Request Parameters
| Parameter Name | Description | Value |
|---------------------------------|-------------------------------------------------|---------------------------------------------------------|
| consumer | | `Type`: **Object** |
| consumer.device | | `Type`: **Object** |
| consumer.device.serial Number | Consumer’s device serial number. | `Type`: String `Length`: 1-50 |
| reference | | `Type`: **Object** |
| reference.server Card Id | The card reference identifier (on server side). | `Type`: String `Length`: 1-64 |
| reference.unique Reference Card Id | The card identifier (on server side). | `Type`: Integer |
| session | | `Type`: **Object** |
| session.access Token | Consumer’s access token key. | `Type`: String `Length`: 32-128 |
| session.token | The session token of verification transaction. | `Type`: String `Length`: 16-36 |
| source Card | | `Type`: **Object** |
| source Card.bin | The Source card BIN. | `Type`: Integer |
#### Success Response Parameters
| Parameter Name | Description | Value |
|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------|
| invoice Id | Verification transaction identifier. | `Type`: String |
| session | | `Type`: **Object** |
| session.check Signature | Checksum generated by hmac-sha1 (see [Signature computation](https://doc.payneteasy.com/integration/api_development_tools.html.md)) from the concatenation of the session.nonce, the endpoint Id and the invoice Id. | `Type`: String |
| session.nonce | Unique random string generated by Connecting Party’s server. | `Type`: String |
| session.token | The session token of verification transaction. | `Type`: String |
#### Fail Response Parameters
| Parameter Name | Description | Value |
|------------------|------------------------------------------------------------------------------------------------------------|------------------------------|
| error | | `Type`: **Object** |
| error.cause | Cause of the error. Possible values: `FILTERED`, `INVALID_REQUEST`, `SERVER_FAILED`, `SERVER_UNAVAILABLE`. | `Type`: Enum |
| error.code | The unique error code. | `Type`: String |
| error.message | Description of the error. | `Type`: String |
| invoice Id | Verification transaction identifier. | `Type`: String |
#### Request Example
```json
{
"consumer": {
"device": {
"serialNumber": "string"
}
},
"reference": {
"serverCardId": "string",
"uniqueReferenceCardId": "integer"
},
"sourceCard": {
"bin": "integer"
},
"session": {
"accessToken": "string",
"token": "string"
}
}
```
#### Success Response Example
```json
{
"invoiceId": "string",
"session": {
"checkSignature": "string",
"nonce": "string",
"token": "string"
}
}
```
#### Fail Response Example
```json
{
"error": {
"cause": "enum",
"code": "string",
"message": "string"
},
"invoiceId": "string"
}
```
### Verification status
#### Introduction
Verification status is initiated through HTTPS POST request by using [URLs](#api-url-verification-status) and the [parameters](#api-parameters-verification-status).
Verification status request is made by Connecting Party’s app to Payneteasy to get the status of verification transaction.
It is recommended to send Verification status request for a period of 2-3 minutes with interval of 3-5 seconds between requests.
Connecting Party’s server should rely on the callback for final status.
#### API URLs
> **Note:** The path in API URL should not be hardcoded, as it may be changed in future.
| Integration | Production |
|-------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/dapi/v1/verification/{endpoint Id}/{invoice Id}/status | https://gate.payneteasy.eu/paynet/dapi/v1/verification/{endpoint Id}/{invoice Id}/status |
#### Request Parameters
| Parameter Name | Description | Value |
|---------------------|--------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| session | | `Necessity`: Required `Type`: **Object** |
| session.access Token | The access token key received in Optional consumer authentication. | `Necessity`: Required `Type`: String `Length`: 32-128 |
| session.token | The session token of verification transaction. | `Necessity`: Required `Type`: String `Length`: 16-36 |
#### Success Response Parameters
| Parameter Name | Description | Value |
|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| invoice Id | Verification transaction identifier. | `Type`: String |
| session | | `Type`: **Object** |
| session.token | The session token of verification transaction. | `Type`: String |
| state | Possible values: `PROCESSING`, `REDIRECT_REQUEST`, `APPROVED`, `DECLINED`. | `Type`: Enum |
| bank Order Id | Required if state is `APPROVED` or `DECLINED`. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| redirect Url | Required if state is `REDIRECT_REQUEST`. | `Necessity`: Conditional `Type`: String `Length`: 128 |
| error Code | Decline reason code, may present if state is `DECLINED`. | `Necessity`: Optional `Type`: Integer `Length`: 128 |
| error Message | Decline reason message, may present if state is `DECLINED`. | `Necessity`: Optional `Type`: String `Length`: 128 |
| secure3DAuth Status | Possible values: `AUTHENTICATED`, `NOT_AUTHENTICATED`, `UNSUPPORTED`, `UNSUPPORTED` means that card does not support 3-D Secure or 3DS authentication process finished with an unknown status. | `Necessity`: Optional `Type`: Enum |
| random Sum Auth Status | Possible values: `AUTHENTICATED`, `NOT_AUTHENTICATED`. | `Necessity`: Optional `Type`: Enum |
#### Fail Response Parameters
| Parameter Name | Description | Value |
|------------------|-------------------------------------------------------------------------------------------------------------------------------|------------------------------|
| error | | `Type`: **Object** |
| error.cause | Cause of the error. Possible values: `FILTERED`, `INVALID_REQUEST`, `INTERNAL_ERROR`, `PROCESSING_FAILED`, `ORDER_NOT_FOUND`. | `Type`: Enum |
| error.code | The unique error code. | `Type`: String |
| error.message | Description of the error. | `Type`: String |
| invoice Id | Verification transaction identifier. | `Type`: String |
#### Request Example
```json
{
"session": {
"accessToken": "string",
"token": "string"
}
}
```
#### Success Response Example
```json
{
"bankOrderId": "string",
"invoiceId": "string",
"redirectUrl": "string",
"session": {
"token": "string"
},
"state": "enum"
}
```
#### Fail Response Example
```json
{
"error": {
"cause": "enum",
"code": "string",
"message": "string"
},
"invoiceId": "string"
}
```
### Apple Pay Web
#### Introduction
Apple Pay is an electronic wallet system that allows Payer to make one-click payment using a card token issued together with Apple and Issuer bank. There is no need to enter card details during Apple Pay transaction. Access to this payment mechanism is possible from any device, which supports Apple Pay. After choosing Apple Pay payment method, the payer will see the form on which he confirms his Apple account and card he is going to use to pay for order. If payer doesn’t have a previously registered card, he may do it while making payment.
See terms definitions in [Glossary](https://doc.payneteasy.com/integration/reference/glossary.html.md).
If accepting payments occurs on the Payneteasy payment page, no additional integration with Apple is required from the Connecting Party.
To use Apple Pay on the Payneteasy payment page, do the following:
1. Enable Apple Pay on the payment page template by adding macro.
2. Inform Payneteasy support about the need to connect Apple Pay and send updated templates.
The Apple Pay button will automatically appear on the Payneteasy checkout page if:
1. The payer uses the Safari browser on a device that supports Apple Pay.
2. The payer has Apple Pay cards available for payment.
> **Note:** It might be necessary for Connecting Party to register [Merchant ID](#register-merchant-id), issue [Payment Processing Certificate](#accountsetup) and [Merchant Identity Certificate](#detailed-instructions-for-domain-verification-and-payment-processing-certificate-registration) in Apple in order to launch Apple Pay. For details please contact Payneteasy support manager.
#### Apple Pay Flow
```plantuml
participant Payer as C
participant "Connecting Party" as cp
autonumber
C -> cp: Checkout
activate cp
alt sale/preauth
cp -> "Payneteasy": sale-form/ENDPOINTID
activate "Payneteasy"
cp -> "Payneteasy": preauth-form/ENDPOINTID
end
"Payneteasy" --> cp: status=processing\nredirect-url
deactivate "Payneteasy"
cp --> C: Provide **redirect-url** to payer's browser
deactivate cp
activate C
loop
cp -> "Payneteasy": Request /api/v2/status
activate cp
activate "Payneteasy"
"Payneteasy" --> cp: status=processing
deactivate cp
deactivate "Payneteasy"
end
C -> "Apple Pay": Check if Apple Pay is supported on Payer's device
activate "Apple Pay"
"Apple Pay" --> C: Apple Pay response
deactivate "Apple Pay"
C -> C: Display Apple Pay button
C -> "Apple Pay": Provide Apple payment data for processing
deactivate C
activate "Apple Pay"
"Apple Pay" --> "Payneteasy": Processing with Apple Pay payment data
deactivate "Apple Pay"
activate "Payneteasy"
"Payneteasy" -> "Payneteasy": Process payment
"Payneteasy" --> C: Redirect to **redirect_url**
activate C
C -> cp: Return to the Shop
deactivate C
activate cp
group Get Final Status
== Receive Connecting Party Callback ==
cp <- "Payneteasy" : callback with final status
"Payneteasy" <-- cp: HTTP 200
deactivate "Payneteasy"
== Order Status request ==
cp -> "Payneteasy": Get status by Order ID\napi/v2/status
activate "Payneteasy"
"Payneteasy" --> cp : Response\nstatus,order-stage
deactivate "Payneteasy"
end
cp --> C: Show result
deactivate cp
```
(2) To implement sale-form payment request see [/api/v2/sale-form](https://doc.payneteasy.com/integration/API_commands/api_v2_sale-form.html.md).
(3) Instead of sale-form it is possible to implement preauth-form payment request, see [/api/v2/preauth-form](https://doc.payneteasy.com/integration/API_commands/api_v2_preauth-form.html.md). Preauth allows to hold the specified amount in the Payer’s card account for a limited time. Preauth can be followed by [Capture](#capture-form-request-url-apple) or [Cancel](#cancel-form-request-url-apple).
(14) Payer is returned to Connecting Party site. To implement final redirect see [Final Redirect](https://doc.payneteasy.com/integration/API_commands/final_redirect.html.md).
(16) To implement callback with final status handling see [Connecting Party Callbacks](https://doc.payneteasy.com/integration/API_commands/merchant_callback_parameters.html.md).
(18) To implement order status request see [/api/v2/status](https://doc.payneteasy.com/integration/API_commands/api_v2_status.html.md). Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.
#### Capture Flow
Capture is a transaction followed after preauth which deducts the locked amount from Payer’s card. It is important to know that the block remains for a definite period of time depending on whether this is a debit or a credit card (usually the maximum block period is 7 days for debit cards and 28 days for credit cards).
```plantuml
skinparam roundcorner 20
skinparam sequenceArrowThickness 1
skinparam maxmessagesize 100
skinparam sequenceParticipant underline
actor Payer
participant "Connecting party" as A
participant "Payneteasy" as B
hnote over A,B : Successful Preauth Transaction
autonumber
group Optional
Payer -> A: Initiate Capture
activate A
end
== Capture ==
A -> B: api/v2/capture
activate B
B --> A: Order ID
B -> B: Process Capture
group Get Final Status
== Receive Callback ==
A <- B: Callback with Final Status
A --> B: HTTP 200
deactivate B
== Order Status Request ==
A -> B: Get Status by Order ID api/v2/status
activate B
B --> A: Response with Status, Order-stage
deactivate B
end
group Optional
A --> Payer: Final Status
deactivate A
end
```
(1) Capture can be initiated by Connecting Party based on internal business model or Payer’s request.
(2) To implement capture request see [/api/v2/capture/](https://doc.payneteasy.com/integration/API_commands/api_v2_capture.html.md).
(5) Callback for Capture will be sent only if notify_url was provided in initial transaction request or additional callback URL for Capture transactions is specified on the endpoint level. If server_callback_url was provided in initial transaction request, callback for Capture will not be sent. To implement callback with final status handling see [Connecting Party Callbacks](https://doc.payneteasy.com/integration/API_commands/merchant_callback_parameters.html.md).
(7) To implement order status request see [/api/v2/status/](https://doc.payneteasy.com/integration/API_commands/api_v2_status.html.md). Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.
(9) Final Status can be sent by Connecting Party based on internal business model or by Payer’s request.
#### Cancel Flow
Cancel is opposite of Capture which cancels the deduction and returns locked by Preauth amount back to Payer’s card. It is important to know that the block remains for a definite period of time depending on whether this is a debit or a credit card (usually the maximum block period is 7 days for debit cards and 28 days for credit cards).
```plantuml
skinparam roundcorner 20
skinparam sequenceArrowThickness 1
skinparam maxmessagesize 100
skinparam sequenceParticipant underline
actor Payer
participant "Connecting party" as A
participant "Payneteasy" as B
hnote over A,B : Successful Preauth Transaction
autonumber
group Optional
Payer -> A: Initiate Cancel
activate A
end
== Cancel ==
A -> B: api/v2/cancel
activate B
B --> A: Order ID
B -> B: Process Cancel
group Get Final Status
== Receive Callback ==
A <- B: Callback with Final Status
A --> B: HTTP 200
deactivate B
== Order Status Request ==
A -> B: Get Status by Order ID api/v2/status
activate B
B --> A: Response with Status, Order-stage
deactivate B
end
group Optional
A --> Payer: Final Status
deactivate A
end
```
(1) Cancel can be initiated by Connecting Party based on internal business model or Payer’s request.
(2) To implement cancel request see [/api/v2/return/](https://doc.payneteasy.com/integration/API_commands/api_v2_return.html.md).
(5) Callback for Cancel will be sent only if notify_url was provided in initial transaction request or additional callback URL for Cancel transactions is specified on the endpoint level. If server_callback_url was provided in initial transaction request, callback for Cancel will not be sent. To implement callback with final status handling see [Connecting Party Callbacks](https://doc.payneteasy.com/integration/API_commands/merchant_callback_parameters.html.md).
(7) To implement order status request see [/api/v2/status/](https://doc.payneteasy.com/integration/API_commands/api_v2_status.html.md). Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.
(9) Final Status can be sent by Connecting Party based on internal business model or by Payer’s request.
#### Apple Pay Account Setup
To configure the terminal on the Payment Gateway side, the following data needs to be sent to the Payneteasy support service:
* Merchant ID.
* The private key of the Payment Processing Certificate.
* Private key password.
To get the necessary data, the following steps are required:
> **Note:** Please note that the Payment Processing Certificate lasts **25 months**. To renew the certificate, see the section “[Reissue of Payment Processing Certificate]()”.
##### Register Merchant ID
Merchant ID - Apple Merchant Site ID (or MID) is a unique identification number that tells the payment processing systems involved in a transaction where to send which funds.
1. Open developer account. Go to Certificate, Identifiers & Profiles.
2. Go to Identifiers.
3. Click on “+”.
4. Select Merchant IDs.
5. Specify the description and the Merchant ID. It is recommended to use the website domain in reverse order with the Connecting Party’s prefix. Example: connecting party.com. Payneteasy.applepay.test.
6. Click Register.
**Merchant ID** is now registered.
##### Create Certificate Signing Request
Certificate Signing Request is a request to issue a certificate, in our case in order to get Payment Processing Certificate.
1. Open Keychain Access on Mac.
2. Certification assistant -> Request a certificate from a Certificate Authority.
3. Specify the email, to which the developer’s account was registered, the name (also key name). Select Saved to disk and Specify information about a pair of keys manually.
4. Select the key size 256 bits and the ECC Algorithm. Click Continue button. Save the .cert Signing Request file.
##### Issue Payment Processing Certificate
1. Return to the developer’s office. Go to Certificates, Identifiers & Profiles / Identifiers. Select needed Merchant ID.
2. Click Create Certificate in Apple Pay Payment Processing Certificate section.
3. Select “No” and click Continue.
4. Choose .cert Signing Request file from step 2 and click Continue.
5. Download **Payment Processing Certificate**.
##### Get the Certificate Private Key and Private Key Password
1. Double click Payment Processing Certificate on Mac to install.
2. Open Keychain Access and go to Certificates section.
3. Find the certificate. Select the created key by clicking on the arrow next to it.
4. Select Export with the right mouse button.
5. Select the folder to save the key file in .p12 format, click Save.
6. Create password and click OK. **Private key** .p12 and **private key password** are ready to work.
##### Reissue of Payment Processing Certificate
The Connecting Party must independently monitor the validity period of the Apple Pay certificate (25 months). Before the certificate expires, a new certificate must be issued.
This requires the following:
1. Create a new Certificate Signing Request, as described in [step 2](#create-certificate-signing-request).
2. Issue a new Payment Processing Certificate as in [step 3](#issue-payment-processing-certificate). After creating a new certificate for the current Merchant ID, there will be two certificates: **old** (active) and **new** (requiring activation). At this step **there is no need** to activate the new certificate.
3. Get the certificate private key, private key password and send them to Payneteasy support service as in [step 4](#get-the-certificate-private-key-and-private-key-password).
4. Activate a new certificate **only in consultation with Payneteasy support service**. After activation, only the new certificate will be used, the old one will become inactive.
#### Merchant Identity Certificate
The following data needs to be sent to the Payneteasy support service:
1. Merchant ID.
2. The private key of the Merchant Identity Certificate.
3. Private key password.
> **Note:** Please note that the validity period of the Merchant Identity Certificate and domain verification is **25 months**. To renew the certificate and re-verify domains, see the section [Re-verification of domains and reissue of the Merchant Identity Certificate](#re-verification).
##### Domain Registration and Verification
> **Warning:** Before receiving the Merchant Identity Certificate, it is compulsory to create and validate domains where Apple Pay will be used.
1. Go to the developer’s office and go to Certificates, Identifiers & Profiles. [Create](#register-merchant-id) a Merchant ID before domain registration.
2. Go to Identifiers.
3. App IDs -> Merchant IDs.
4. Select the needed Merchant ID.
5. Click Add Domain in Merchant Domains.
6. Specify the domain where Apple Pay will be used and click Save.
7. To confirm ownership of a domain, download the file and place ot at the specified address, the file at the specified address must be accessible from outside the Connecting Party’s network.
8. Click Verify to verify the domain.
##### Creation of Merchant Identity Certificate
Step 1. [Create Certificate Signing Request]()
Step 2. [Issue Merchant Identity Certificate]()
Step 3. [Get the certificate private key and private key password]()
##### Create Certificate Signing Request
Certificate Signing Request is a request to issue a certificate, in our case in order to get Payment Processing Certificate.
1. Open Keychain Access on Mac.
2. Certification assistant -> Request a certificate from a Certificate Authority.
3. Specify the email, to which the developer’s account was registered, the name (also key name). Select Saved to disk and Specify information about a pair of keys manually.
4. Select the key size 2048 bits and the RSA Algorithm. Click Continue button. Save the .cert Signing Request file.
##### Issue Merchant Identity Certificate
1. Return to the developer’s office. Go to Certificates, Identifiers & Profiles / Identifiers.
2. Go to Identifiers.
3. App IDs -> Merchant IDs.
4. Select the needed Merchant ID.
5. Create Certificate in Apple Pay Merchant Identity Certificate section.
6. Select created in step 1 .cert Signing Request file and click Continue.
7. Download **Merchant Identity Certificate**.
##### Get the Certificate Private Key and Private Key Password
1. Double click Merchant Identity Certificate on Mac to install.
2. Open Keychain Access and go to Certificates section.
3. Find the certificate. Select Export with the right mouse button.
4. Select the folder to save the key file in .p12 format, click Save.
5. Create password and click OK. **Private key** .p12 and **private key password** are ready to work.
##### Domain Re-verification and Merchant Identity Certificate Reissue
The Connecting Party must independently monitor the validity of the certificate and domains’ verification (25 months).
A new Merchant Identity Certificate must be issued before the certificate expires. Certificates can be used concurrently, so the procedure for issuing a new one is as described in the “Creating a Merchant Identity Certificate” section.
Before the expiration of the domain verification period, the Verify button is activated next to it.
The verification procedure corresponds to that described in the section “Domain registration and verification”.
### Async-Response
```plantuml
@startuml
participant cp as "Connecting Party"
participant paynet as "Payneteasy"
==Request Initiation==
cp -> paynet: API Request
activate cp
activate paynet
paynet --> cp: Order ID
deactivate cp
deactivate paynet
==Order Status Request==
cp -> paynet: api/v2/status
activate cp
activate paynet
paynet --> cp: Response\nstatus, order-stage
deactivate cp
deactivate paynet
==Receive Merchant Callback==
paynet -> cp: callback with final status
activate cp
activate paynet
cp --> paynet: HTTP 200
deactivate cp
deactivate paynet
@enduml
```
Unless explicitly stated otherwise in relevant API command, all Payneteasy responses are asynchronous, regardless of the request or callback sent.
### Bank transfer with Invoice
#### Introduction
This Use-Case describes how Connecting Party can issue invoices for Swift or similar wire bank transfer systems in Payment Gateway and display these invoices to Payers. Incoming bank transfer statuses might be updated automatically or manually.
See terms definitions in [Glossary](https://doc.payneteasy.com/integration/reference/glossary.html.md).
#### Bank Wire Transfer Flow
```plantuml
skinparam roundcorner 20
skinparam sequenceArrowThickness 2
skinparam ParticipantPadding 30
actor Payer as Customer
participant "Connecting Party\nwebsite" as Merchant
participant "Payment Gateway" as g
autonumber
Customer -> Merchant: Checkout
activate Merchant
== Purchase payment request ==
Merchant -> g: api/v2/auth-cash
activate g
g --> Merchant: orderId
g --> g: Generating payment invoice
== Receive Connecting Party Callback ==
Merchant <- g: Сallback with final status
g <-- Merchant: HTTP 200
deactivate g
== Order Status Request ==
Merchant -> g: api/v2/status
activate g
g --> Merchant: Response \nstatus, order-stage, receipt-id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
deactivate g
== Get invoice in XML, PDF or both ==
group XML
g <-- Merchant: view-invoice-xml/ENDPOINTID/receipt-id
activate g
g --> Merchant: XML
deactivate g
end
group PDF
g <-- Merchant: view-invoice/ENDPOINTID/receipt-id
activate g
g --> Merchant: PDF
deactivate g
end
Merchant -> Customer: Show result
deactivate Merchant
```
(2) To implement bank transfer request see [/api/v2/auth-cash/](https://doc.payneteasy.com/integration/API_commands/api_v2_auth-cash.html.md).
(5,6) To implement order status request see [/api/v2/status/](https://doc.payneteasy.com/integration/API_commands/api_v2_status.html.md). Status should be requested multiple times with 3-5 seconds interval until final status will be received in response. receipt-id will be received in status response.
(7) To implement callback with final status handling see [Connecting Party](https://doc.payneteasy.com/integration/API_commands/merchant_callback_parameters.html.md).
(9) To implement view-invoice-xml request see [/view-invoice-xml/](https://doc.payneteasy.com/integration/API_commands/view-invoice-xml.html.md). receipt-id will be used to get invoice in XML format.
(11) To implement view-invoice request see [/view-invoice/](https://doc.payneteasy.com/integration/API_commands/view-invoice.html.md). receipt-id will be used to get invoice in PDF format.
#### Simple Bank Transfer Flow Statuses
| Stage name | Description |
|-------------------|---------------------------------------------------------------------------------------------------------------------------|
| AUTH_APPROVED | Invoice was issued for the Payer. |
| CANCEL_APPROVED | Payer didn’t complete the transfer. This stage is optional and may be used for better transaction control in back-office. |
| CAPTURE_APPROVED | Funds were transferred to the Connecting Party account (settled). |
| VOID_APPROVED | Funds were returned by the Payer (recalled). |
| REVERSAL_APPROVED | Funds were returned to the Payer by Connecting Party. |
#### Extended Bank Transfer Flow Statuses
| Stage name | Description |
|---------------------|---------------------------------------------------------------------------------------------------------------------------|
| AUTH_STARTING | Transaction was initiated. |
| AUTH_INVOICED | Invoice was issued for the Payer. It may be downloaded in back-office, sent to Payer by e-mail or requested via API. |
| AUTH_SENT | Payer informed the Connecting Party that invoice have been paid. This stage may be skipped. |
| CANCEL_APPROVED | Payer didn’t complete the transfer. This stage is optional and may be used for better transaction control in back-office. |
| AUTH_APPROVED | Transfer was received by the bank. |
| CAPTURE_APPROVED | Funds were transferred to the Connecting Party account (settled). |
| VOID_APPROVED | Funds were returned by the Payer (recalled). |
| REVERSAL_APPROVED | Funds were returned to the Payer by Connecting Party. |
| CHARGEBACK_APPROVED | Funds were charged back by the Payer. |
### Bitrix24
The Bitrix24 (1C-Bitrix) plugin is a payment module that adds Payneteasy as a payment system handler inside a Bitrix online store. It is distributed as a PHP module folder that is uploaded to the site via FTP and then activated through the Bitrix Marketplace, after which it can be selected as a payment handler for a store’s payment systems.
Documentation for this plugin is intentionally brief, since it mostly points to the plugin’s source repository and the (Russian- and English-language) installation notes published alongside it.
#### Source code
The plugin source is published on Git Hub: [php-plugin-bitrix](https://github.com/payneteasy/php-plugin-bitrix). The repository contains the plugin module itself, in a folder named `payneteasypayments.ecom`, together with a plain-text installation guide.
An accompanying documentation repository is also available: [bitrix-doc](https://github.com/annihilatoratm/bitrix-doc), which links to an [English-language installation guide](https://github.com/annihilatoratm/bitrix-doc/blob/main/documentation/doc-eng.md).
### Buy Now Button
#### Introduction
Buy Now Button integration is relevant for Connecting Party who has limited portfolio of products to sell. It is the easiest way to integrate with Payneteasy. This way of integration doesn’t require much technical effort. Buy Now Button integration also allows Connecting Party to exclude itself from storing, processing, or transmitting Payer’s cardholder data or other sensitive payment details. Such data is submitted by Payer on Payneteasy hosted customer details form and payment form in PCI DSS certified environment.
See terms definitions in [Glossary](https://doc.payneteasy.com/integration/reference/glossary.html.md).
1. Payer clicks on Buy Now Button, gets redirected to customer details form provided by Payment Gateway and submits customer data;
`Buy Now Button Form`
1. Payers then gets redirected to payment form and submits payment (cardholder) data.
1. Contextual data is gathered by Payneteasy to process the transaction, Payer stays on wait form until transaction is finished;
1. Payer’s browser gets redirected to the Connecting Party website to the resultant page.
#### Required Parameters for Buy Now Button Integration
Connecting Party provides to Payment Gateway support the following information for each product (item): Amount, Description, Final Redirect URL, Destination (purpose of payment) and Payment tool (payment method).
Payment Gateway provides to Connecting Party the Buy Now Button URLs for each product (item). URLs have the following format:
| Integration | Production |
|-------------------------------------------------------------------|----------------------------------------------------------------|
| https://sandbox.payneteasy.eu/paynet/api/v2/pay/ENDPOINTID/ITEMID | https://gate.payneteasy.eu/paynet/api/v2/pay/ENDPOINTID/ITEMID |
#### Buy Now Button Form Flow
```plantuml
skinparam roundcorner 20
skinparam sequenceArrowThickness 2
skinparam ParticipantPadding 30
actor Payer as Customer
participant "Connecting Party\nwebsite" as Merchant
participant "Payment Gateway" as g
autonumber
Customer -> Merchant: Checkout
activate Customer
activate Merchant
Customer <-- Merchant: Display Buy Now Button
deactivate Merchant
Customer -> g: Redirect to Buy Now Button form
activate g
g --> Customer: Return customer details form
deactivate g
g <- Customer: Submit customer details form
activate g
g --> Customer: Return payment form
deactivate g
Customer -> g: Submit payment form
deactivate Customer
activate g
g --> g: Process payment
== Final redirect of customer ==
g -> Customer: Connecting Party website redirect_url
activate Customer
Customer -> Merchant: POST redirect_url\nstatus, orderid
deactivate Customer
activate Merchant
group Get Final Status
== Receive Connecting Party Callback ==
Merchant <- g: Сallback with final status
g <-- Merchant: HTTP 200
deactivate g
== Order Status Request ==
Merchant -> g: api/v2/status
activate g
g --> Merchant: Response \nstatus, order-stage
deactivate g
end
Merchant -> Customer: Show result
deactivate Merchant
```
(2) Place the Buy Now Button HTML element on checkout page available for the Payer.
(9) To implement final redirect see [Final Redirect](https://doc.payneteasy.com/integration/API_commands/final_redirect.html.md).
(11,12) To implement order status request see [/api/v2/status/](https://doc.payneteasy.com/integration/API_commands/api_v2_status.html.md). Connecting Party may request order status after receiving transaction ID in either Connecting Party callback or final redirect.
(13) To implement callback with final status handling see [Connecting Party Callbacks](https://doc.payneteasy.com/integration/API_commands/merchant_callback_parameters.html.md).
### Common Utilities
### Country and State Codes
#### Country Codes
* Alpha-2 country codes are used in country field.
* Alpha-3 codes are returned in status response and callback in card-country-alpha-three-code and destination-card-country-alpha-three-code parameters.
* ISO Codes are used in Payment Gateway configurations.
| Country | Alpha-2 Code | Alpha-3 Code | ISO Code |
|----------------------------------------------|----------------|----------------|------------|
| Åland Islands | AX | ALA | 248 |
| Afghanistan | AF | AFG | 004 |
| Albania | AL | ALB | 008 |
| Algeria | DZ | DZA | 012 |
| American Samoa | AS | ASM | 016 |
| Andorra | AD | AND | 020 |
| Angola | AO | AGO | 024 |
| Anguilla | AI | AIA | 660 |
| Antarctica | AQ | ATA | 010 |
| Antigua and Barbuda | AG | ATG | 028 |
| Argentina | AR | ARG | 032 |
| Armenia | AM | ARM | 051 |
| Aruba | AW | ABW | 533 |
| Australia | AU | AUS | 036 |
| Austria | AT | AUT | 040 |
| Azerbaijan | AZ | AZE | 031 |
| Bahamas | BS | BHS | 044 |
| Bahrain | BH | BHR | 048 |
| Bangladesh | BD | BGD | 050 |
| Barbados | BB | BRB | 052 |
| Belarus | BY | BLR | 112 |
| Belgium | BE | BEL | 056 |
| Belize | BZ | BLZ | 084 |
| Benin | BJ | BEN | 204 |
| Bermuda | BM | BMU | 060 |
| Bhutan | BT | BTN | 064 |
| Bolivia, Plurinational State of | BO | BOL | 068 |
| Bosnia and Herzegovina | BA | BIH | 070 |
| Botswana | BW | BWA | 072 |
| Bouvet Island | BV | BVT | 074 |
| Brazil | BR | BRA | 076 |
| British Indian Ocean Territory | IO | IOT | 086 |
| Brunei Darussalam | BN | BRN | 096 |
| Bulgaria | BG | BGR | 100 |
| Burkina Faso | BF | BFA | 854 |
| Burundi | BI | BDI | 108 |
| Cambodia | KH | KHM | 116 |
| Cameroon | CM | CMR | 120 |
| Canada | CA | CAN | 124 |
| Cabo Verde | CV | CPV | 132 |
| Cayman Islands | KY | CYM | 136 |
| Central African Republic | CF | CAF | 140 |
| Chad | TD | TCD | 148 |
| Chile | CL | CHL | 152 |
| China | CN | CHN | 156 |
| Christmas Island | CX | CXR | 162 |
| Cocos (Keeling) Islands | CC | CCK | 166 |
| Colombia | CO | COL | 170 |
| Comoros | KM | COM | 174 |
| Congo | CG | COG | 178 |
| Congo, the Democratic Republic of the | CD | COD | 180 |
| Cook Islands | CK | COK | 184 |
| Costa Rica | CR | CRI | 188 |
| Cote d’Ivoire | CI | CIV | 384 |
| Croatia | HR | HRV | 191 |
| Cuba | CU | CUB | 192 |
| Cyprus | CY | CYP | 196 |
| Czechia | CZ | CZE | 203 |
| Denmark | DK | DNK | 208 |
| Djibouti | DJ | DJI | 262 |
| Dominica | DM | DMA | 212 |
| Dominican Republic | DO | DOM | 214 |
| Ecuador | EC | ECU | 218 |
| Egypt | EG | EGY | 818 |
| El Salvador | SV | SLV | 222 |
| Equatorial Guinea | GQ | GNQ | 226 |
| Eritrea | ER | ERI | 232 |
| Estonia | EE | EST | 233 |
| Ethiopia | ET | ETH | 231 |
| Falkland Islands (Malvinas) | FK | FLK | 238 |
| Faroe Islands | FO | FRO | 234 |
| Fiji | FJ | FJI | 242 |
| Finland | FI | FIN | 246 |
| France | FR | FRA | 250 |
| French Guiana | GF | GUF | 254 |
| French Polynesia | PF | PYF | 258 |
| French Southern Territories | TF | ATF | 260 |
| Gabon | GA | GAB | 266 |
| Gambia | GM | GMB | 270 |
| Georgia | GE | GEO | 268 |
| Germany | DE | DEU | 276 |
| Ghana | GH | GHA | 288 |
| Gibraltar | GI | GIB | 292 |
| Greece | GR | GRC | 300 |
| Greenland | GL | GRL | 304 |
| Grenada | GD | GRD | 308 |
| Guadeloupe | GP | GLP | 312 |
| Guam | GU | GUM | 316 |
| Guatemala | GT | GTM | 320 |
| Guernsey | GG | GGY | 831 |
| Guinea | GN | GIN | 324 |
| Guinea-Bissau | GW | GNB | 624 |
| Guyana | GY | GUY | 328 |
| Haiti | HT | HTI | 332 |
| Heard Island and Mc Donald Islands | HM | HMD | 334 |
| Holy See (Vatican City State) | VA | VAT | 336 |
| Honduras | HN | HND | 340 |
| Hong Kong | HK | HKG | 344 |
| Hungary | HU | HUN | 348 |
| Iceland | IS | ISL | 352 |
| India | IN | IND | 356 |
| Indonesia | ID | IDN | 360 |
| Iran, Islamic Republic of | IR | IRN | 364 |
| Iraq | IQ | IRQ | 368 |
| Ireland | IE | IRL | 372 |
| Isle of Man | IM | IMN | 833 |
| Israel | IL | ISR | 376 |
| Italy | IT | ITA | 380 |
| Jamaica | JM | JAM | 388 |
| Japan | JP | JPN | 392 |
| Jersey | JE | JEY | 832 |
| Jordan | JO | JOR | 400 |
| Kazakhstan | KZ | KAZ | 398 |
| Kenya | KE | KEN | 404 |
| Kosovo | XK | XKX | 983 |
| Kiribati | KI | KIR | 296 |
| Korea, Democratic People’s Republic of | KP | PRK | 408 |
| Korea, Republic of | KR | KOR | 410 |
| Kuwait | KW | KWT | 414 |
| Kyrgyzstan | KG | KGZ | 417 |
| Lao People’s Democratic Republic | LA | LAO | 418 |
| Latvia | LV | LVA | 428 |
| Lebanon | LB | LBN | 422 |
| Lesotho | LS | LSO | 426 |
| Liberia | LR | LBR | 430 |
| Libya | LY | LBY | 434 |
| Liechtenstein | LI | LIE | 438 |
| Lithuania | LT | LTU | 440 |
| Luxembourg | LU | LUX | 442 |
| Macao | MO | MAC | 446 |
| North Macedonia | MK | MKD | 807 |
| Madagascar | MG | MDG | 450 |
| Malawi | MW | MWI | 454 |
| Malaysia | MY | MYS | 458 |
| Maldives | MV | MDV | 462 |
| Mali | ML | MLI | 466 |
| Malta | MT | MLT | 470 |
| Marshall Islands | MH | MHL | 584 |
| Martinique | MQ | MTQ | 474 |
| Mauritania | MR | MRT | 478 |
| Mauritius | MU | MUS | 480 |
| Mayotte | YT | MYT | 175 |
| Mexico | MX | MEX | 484 |
| Micronesia, Federated States of | FM | FSM | 583 |
| Moldova, Republic of | MD | MDA | 498 |
| Monaco | MC | MCO | 492 |
| Mongolia | MN | MNG | 496 |
| Montenegro | ME | MNE | 499 |
| Montserrat | MS | MSR | 500 |
| Morocco | MA | MAR | 504 |
| Mozambique | MZ | MOZ | 508 |
| Myanmar | MM | MMR | 104 |
| Namibia | NA | NAM | 516 |
| Nauru | NR | NRU | 520 |
| Nepal | NP | NPL | 524 |
| Netherlands | NL | NLD | 528 |
| New Caledonia | NC | NCL | 540 |
| New Zealand | NZ | NZL | 554 |
| Nicaragua | NI | NIC | 558 |
| Niger | NE | NER | 562 |
| Nigeria | NG | NGA | 566 |
| Niue | NU | NIU | 570 |
| Norfolk Island | NF | NFK | 574 |
| Northern Mariana Islands | MP | MNP | 580 |
| Norway | NO | NOR | 578 |
| Oman | OM | OMN | 512 |
| Pakistan | PK | PAK | 586 |
| Palau | PW | PLW | 585 |
| Palestine, State of | PS | PSE | 275 |
| Panama | PA | PAN | 591 |
| Papua New Guinea | PG | PNG | 598 |
| Paraguay | PY | PRY | 600 |
| Peru | PE | PER | 604 |
| Philippines | PH | PHL | 608 |
| Pitcairn | PN | PCN | 612 |
| Poland | PL | POL | 616 |
| Portugal | PT | PRT | 620 |
| Puerto Rico | PR | PRI | 630 |
| Qatar | QA | QAT | 634 |
| Reunion | RE | REU | 638 |
| Romania | RO | ROU | 642 |
| Russian Federation | RU | RUS | 643 |
| Rwanda | RW | RWA | 646 |
| Saint Barthelemy | BL | BLM | 652 |
| Saint Helena, Ascension and Tristan da Cunha | SH | SHN | 654 |
| Saint Kitts and Nevis | KN | KNA | 659 |
| Saint Lucia | LC | LCA | 662 |
| Saint Martin (French part) | MF | MAF | 663 |
| Saint Pierre and Miquelon | PM | SPM | 666 |
| Saint Vincent and the Grenadines | VC | VCT | 670 |
| Samoa | WS | WSM | 882 |
| San Marino | SM | SMR | 674 |
| Sao Tome and Principe | ST | STP | 678 |
| Saudi Arabia | SA | SAU | 682 |
| Senegal | SN | SEN | 686 |
| Serbia | RS | SRB | 688 |
| Seychelles | SC | SYC | 690 |
| Sierra Leone | SL | SLE | 694 |
| Singapore | SG | SGP | 702 |
| Slovakia | SK | SVK | 703 |
| Slovenia | SI | SVN | 705 |
| Solomon Islands | SB | SLB | 090 |
| Somalia | SO | SOM | 706 |
| South Africa | ZA | ZAF | 710 |
| South Georgia and the South Sandwich Islands | GS | SGS | 239 |
| Spain | ES | ESP | 724 |
| Sri Lanka | LK | LKA | 144 |
| Sudan | SD | SDN | 729 |
| Suriname | SR | SUR | 740 |
| Svalbard and Jan Mayen | SJ | SJM | 744 |
| Eswatini | SZ | SWZ | 748 |
| Sweden | SE | SWE | 752 |
| Switzerland | CH | CHE | 756 |
| Syrian Arab Republic | SY | SYR | 760 |
| Taiwan, Province of China | TW | TWN | 158 |
| Tajikistan | TJ | TJK | 762 |
| Tanzania, United Republic of | TZ | TZA | 834 |
| Thailand | TH | THA | 764 |
| Timor-Leste | TL | TLS | 626 |
| Togo | TG | TGO | 768 |
| Tokelau | TK | TKL | 772 |
| Tonga | TO | TON | 776 |
| Trinidad and Tobago | TT | TTO | 780 |
| Tunisia | TN | TUN | 788 |
| Türkiye | TR | TUR | 792 |
| Turkmenistan | TM | TKM | 795 |
| Turks and Caicos Islands | TC | TCA | 796 |
| Tuvalu | TV | TUV | 798 |
| Uganda | UG | UGA | 800 |
| Ukraine | UA | UKR | 804 |
| United Arab Emirates | AE | ARE | 784 |
| United Kingdom | GB | GBR | 826 |
| United States | US | USA | 840 |
| United States Minor Outlying Islands | UM | UMI | 581 |
| Uruguay | UY | URY | 858 |
| Uzbekistan | UZ | UZB | 860 |
| Vanuatu | VU | VUT | 548 |
| Venezuela, Bolivarian Republic of | VE | VEN | 862 |
| Viet Nam | VN | VNM | 704 |
| Virgin Islands, British | VG | VGB | 092 |
| Virgin Islands, U.S. | VI | VIR | 850 |
| Wallis and Futuna | WF | WLF | 876 |
| Western Sahara | EH | ESH | 732 |
| Yemen | YE | YEM | 887 |
| Zambia | ZM | ZMB | 894 |
| Zimbabwe | ZW | ZWE | 716 |
| Sint Maarten (Dutch part) | SX | SXM | 534 |
| Curaçao | CW | CUW | 531 |
| Bonaire, Sint Eustatius and Saba | BQ | BES | 535 |
| South Sudan | SS | SSD | 728 |
#### Mandatory State Codes
Mandatory state codes used in state field for USA, Canada and Australia.
| Country | State Code | State Name |
|-----------|--------------|------------------------------|
| AU | ACT | Australian Capital Territory |
| AU | NSW | New South Wales |
| AU | NT | Northern Territory |
| AU | QLD | Queensland |
| AU | SA | South Australia |
| AU | TAS | Tasmania |
| AU | VIC | Victoria |
| AU | WA | Western Australia |
| CA | AB | Alberta |
| CA | BC | British Columbia |
| CA | MB | Manitoba |
| CA | NB | New Brunswick |
| CA | NL | Newfoundland and Labrador |
| CA | NT | Northwest Territories |
| CA | NS | Nova Scotia |
| CA | NU | Nunavut |
| CA | ON | Ontario |
| CA | PE | Prince Edward Island |
| CA | QC | Quebec |
| CA | SK | Saskatchewan |
| CA | YT | Yukon |
| US | AL | Alabama |
| US | AK | Alaska |
| US | AS | American Samoa |
| US | AZ | Arizona |
| US | AR | Arkansas |
| US | CA | California |
| US | CO | Colorado |
| US | CT | Connecticut |
| US | DE | Delaware |
| US | DC | District of Columbia |
| US | FL | Florida |
| US | GA | Georgia |
| US | GU | Guam |
| US | HI | Hawaii |
| US | ID | Idaho |
| US | IL | Illinois |
| US | IN | Indiana |
| US | IA | Iowa |
| US | KS | Kansas |
| US | KY | Kentucky |
| US | LA | Louisiana |
| US | ME | Maine |
| US | MD | Maryland |
| US | MA | Massachusetts |
| US | MI | Michigan |
| US | MN | Minnesota |
| US | MS | Mississippi |
| US | MO | Missouri |
| US | MT | Montana |
| US | NE | Nebraska |
| US | NV | Nevada |
| US | NH | New Hampshire |
| US | NJ | New Jersey |
| US | NM | New Mexico |
| US | NY | New York |
| US | NC | North Carolina |
| US | ND | North Dakota |
| US | OH | Ohio |
| US | OK | Oklahoma |
| US | OR | Oregon |
| US | PA | Pennsylvania |
| US | PR | Puerto Rico |
| US | RI | Rhode Island |
| US | SC | South Carolina |
| US | SD | South Dakota |
| US | TN | Tennessee |
| US | TX | Texas |
| US | UT | Utah |
| US | VT | Vermont |
| US | VI | Virgin Islands |
| US | VA | Virginia |
| US | WA | Washington |
| US | WV | West Virginia |
| US | WI | Wisconsin |
| US | WY | Wyoming |
#### Other State Codes
Optional state codes used in state field. Depending on the processing channel these codes can also be mandatory.
| Country | ISO 3166-2 Сode | State Name |
|-----------|-------------------|-----------------------------------------------------------------------------|
| AF | BDS | Badakhshan |
| AF | BDG | Badghis |
| AF | BGL | Baghlan |
| AF | BAL | Balkh |
| AF | BAM | Bamian |
| AF | FRA | Farah |
| AF | FYB | Faryab |
| AF | GHA | Ghazni |
| AF | GHO | Ghowr |
| AF | HEL | Helmand |
| AF | HER | Herat |
| AF | JOW | Jowzjan |
| AF | KAB | Kabul |
| AF | KAN | Kandahar |
| AF | KAP | Kapisa |
| AF | KHO | Khost |
| AF | KNR | Konar |
| AF | KDZ | Kondoz |
| AF | LAG | Laghman |
| AF | NAN | Nangrahar |
| AF | NIM | Nimruz |
| AF | NUR | Nurestan |
| AF | PIA | Paktia |
| AF | PKA | Paktika |
| AF | PAR | Parwan |
| AF | SAM | Samangan |
| AF | SAR | Sar-e Pol |
| AF | TAK | Takhar |
| AF | WAR | Wardak |
| AF | DAY | Dāykundī |
| AF | LOG | Lōgar |
| AF | PAN | Panjshayr |
| AF | URU | Uruzgān |
| AF | ZAB | Zābul |
| AL | 01 | Berat |
| AL | 09 | Diber |
| AL | 02 | Durres |
| AL | 03 | Elbasan |
| AL | 04 | Fier |
| AL | 05 | Gjirokaster |
| AL | 06 | Korce |
| AL | 07 | Kukes |
| AL | 08 | Lezhe |
| AL | 10 | Shkoder |
| AL | 11 | Tirane |
| AL | 12 | Vlore |
| DZ | 01 | Adrar |
| DZ | 44 | Ain Defla |
| DZ | 46 | Ain Temouchent |
| DZ | 16 | Alger |
| DZ | 23 | Annaba |
| DZ | 05 | Batna |
| DZ | 08 | Bechar |
| DZ | 06 | Bejaia |
| DZ | 07 | Biskra |
| DZ | 09 | Blida |
| DZ | 34 | Bordj Bou Arreridj |
| DZ | 10 | Bouira |
| DZ | 35 | Boumerdes |
| DZ | 02 | Chlef |
| DZ | 25 | Constantine |
| DZ | 17 | Djelfa |
| DZ | 32 | El Bayadh |
| DZ | 39 | El Oued |
| DZ | 36 | El Tarf |
| DZ | 47 | Ghardaia |
| DZ | 24 | Guelma |
| DZ | 33 | Illizi |
| DZ | 18 | Jijel |
| DZ | 40 | Khenchela |
| DZ | 03 | Laghouat |
| DZ | 28 | M’Sila |
| DZ | 26 | Medea |
| DZ | 43 | Mila |
| DZ | 27 | Mostaganem |
| DZ | 45 | Naama |
| DZ | 31 | Oran |
| DZ | 30 | Ouargla |
| DZ | 48 | Relizane |
| DZ | 20 | Saida |
| DZ | 19 | Setif |
| DZ | 22 | Sidi Bel Abbes |
| DZ | 21 | Skikda |
| DZ | 41 | Souk Ahras |
| DZ | 12 | Tebessa |
| DZ | 14 | Tiaret |
| DZ | 37 | Tindouf |
| DZ | 42 | Tipaza |
| DZ | 38 | Tissemsilt |
| DZ | 15 | Tizi Ouzou |
| DZ | 13 | Tlemcen |
| DZ | 04 | Oum el Bouaghi |
| DZ | 11 | Tamanrasset |
| DZ | 29 | Mascara |
| AD | 07 | Andorra la Vella |
| AD | 02 | Canillo |
| AD | 03 | Encamp |
| AD | 08 | Escaldes-Engordany |
| AD | 04 | La Massana |
| AD | 05 | Ordino |
| AD | 06 | Sant Julia de Loria |
| AO | BGO | Bengo |
| AO | BGU | Benguela |
| AO | BIE | Bie |
| AO | CAB | Cabinda |
| AO | CCU | Cuando-Cubango |
| AO | CNO | Cuanza Norte |
| AO | CUS | Cuanza Sul |
| AO | CNN | Cunene |
| AO | HUA | Huambo |
| AO | HUI | Huila |
| AO | LUA | Luanda |
| AO | LNO | Lunda Norte |
| AO | LSU | Lunda Sul |
| AO | MAL | Malange |
| AO | MOX | Moxico |
| AO | NAM | Namibe |
| AO | UIG | Uige |
| AO | ZAI | Zaire |
| AG | 10 | Barbuda |
| AG | 11 | Redonda |
| AG | 03 | Saint George |
| AG | 04 | Saint John |
| AG | 05 | Saint Mary |
| AG | 06 | Saint Paul |
| AG | 07 | Saint Peter |
| AG | 08 | Saint Philip |
| AR | B | Buenos Aires |
| AR | K | Catamarca |
| AR | H | Chaco |
| AR | U | Chubut |
| AR | X | Cordoba |
| AR | W | Corrientes |
| AR | E | Entre Rios |
| AR | P | Formosa |
| AR | Y | Jujuy |
| AR | L | La Pampa |
| AR | F | La Rioja |
| AR | M | Mendoza |
| AR | N | Misiones |
| AR | Q | Neuquen |
| AR | R | Rio Negro |
| AR | A | Salta |
| AR | J | San Juan |
| AR | D | San Luis |
| AR | Z | Santa Cruz |
| AR | S | Santa Fe |
| AR | G | Santiago del Estero |
| AR | V | Tierra del Fuego |
| AR | T | Tucuman |
| AR | C | Ciudad Autónoma de Buenos Aires |
| AM | AR | Ararat |
| AM | AV | Armavir |
| AM | KT | Kotayk’ |
| AM | SU | Syunik’ |
| AM | AG | Aragac̣otn |
| AM | ER | Erevan |
| AM | GR | Geġark’unik’ |
| AM | LO | Loṙi |
| AM | SH | Širak |
| AM | TV | Tavuš |
| AM | VD | Vayoć Jor |
| AT | 1 | Burgenland |
| AT | 3 | Niederösterreich |
| AT | 5 | Salzburg |
| AT | 6 | Steiermark |
| AT | 7 | Tirol |
| AT | 8 | Vorarlberg |
| AT | 9 | Wien |
| AT | 2 | Kärnten |
| AT | 4 | Oberösterreich |
| AZ | ABS | Abseron |
| AZ | AGC | Agcab Adi |
| AZ | AGM | Agdam |
| AZ | AGS | Agdas |
| AZ | AGA | Agstafa |
| AZ | AGU | Agsu |
| AZ | AST | Astara |
| AZ | BAR | BArdA |
| AZ | BAB | Bab Ak |
| AZ | BA | Baki |
| AZ | BAL | Balak An |
| AZ | BEY | Beylaqan |
| AZ | BIL | Bilasuvar |
| AZ | CAB | Cabrayil |
| AZ | CAL | Calilabab |
| AZ | CUL | Culfa |
| AZ | DAS | Daskasan |
| AZ | FUZ | Fuzuli |
| AZ | GAD | Gadabay |
| AZ | GA | Ganca |
| AZ | GOR | Goranboy |
| AZ | GOY | Goycay |
| AZ | HAC | Haciqabul |
| AZ | IMI | Imisli |
| AZ | ISM | Ismayilli |
| AZ | KAL | Kalbacar |
| AZ | KUR | Kurdamir |
| AZ | LAC | Lacin |
| AZ | LA | Lankaran |
| AZ | LER | Lerik |
| AZ | MAS | Masalli |
| AZ | MI | Mingacevir |
| AZ | NA | Naftalan |
| AZ | NX | Naxcivan |
| AZ | NEF | Neftcala |
| AZ | OGU | Oguz |
| AZ | ORD | Ordubad |
| AZ | QAB | Qabala |
| AZ | QAX | Qax |
| AZ | QAZ | Qazax |
| AZ | QOB | Qobustan |
| AZ | QBA | Quba |
| AZ | QBI | Qubadli |
| AZ | QUS | Qusar |
| AZ | SAT | Saatli |
| AZ | SAB | Sabirabad |
| AZ | SAD | Sadarak |
| AZ | SAH | Sahbuz |
| AZ | SA | Saki |
| AZ | SAL | Salyan |
| AZ | SMI | Samaxi |
| AZ | SKR | Samkir |
| AZ | SMX | Samux |
| AZ | SAR | Sarur |
| AZ | SIY | Siyazan |
| AZ | SM | Sumqayit |
| AZ | SUS | Susa |
| AZ | TAR | Tartar |
| AZ | TOV | Tovuz |
| AZ | UCA | Ucar |
| AZ | XAC | Xacmaz |
| AZ | XA | Xankandi |
| AZ | XIZ | Xizi |
| AZ | XCI | Xocali |
| AZ | XVD | Xocavand |
| AZ | YAR | Yardimli |
| AZ | YE | Yevlax |
| AZ | ZAN | Zangilan |
| AZ | ZAQ | Zaqatala |
| AZ | ZAR | Zardab |
| AZ | GYG | Göygöl |
| AZ | KAN | Kǝngǝrli |
| AZ | SBN | Şabran |
| AZ | SR | Şirvan |
| BS | AK | Acklins |
| BS | BY | Berry Islands |
| BS | BI | Bimini |
| BS | BP | Black Point |
| BS | CI | Cat Island |
| BS | CO | Central Abaco |
| BS | CS | Central Andros |
| BS | CE | Central Eleuthera |
| BS | FP | City of Freeport |
| BS | EG | East Grand Bahama |
| BS | EX | Exuma |
| BS | GC | Grand Cay |
| BS | HI | Harbour Island |
| BS | HT | Hope Town |
| BS | IN | Inagua |
| BS | LI | Long Island |
| BS | MC | Mangrove Cay |
| BS | MG | Mayaguana |
| BS | MI | Moore’s Island |
| BS | NO | North Abaco |
| BS | NS | North Andros |
| BS | NE | North Eleuthera |
| BS | RI | Ragged Island |
| BS | RC | Rum Cay |
| BS | SS | San Salvador |
| BS | SO | South Abaco |
| BS | SA | South Andros |
| BS | SE | South Eleuthera |
| BS | SW | Spanish Wells |
| BS | WG | West Grand Bahama |
| BS | CK | Crooked Island and Long Cay |
| BS | NP | New Providence |
| BH | 13 | Al ‘Āşimah |
| BH | 14 | Al Janūbīyah |
| BH | 15 | Al Muḩarraq |
| BH | 17 | Ash Shamālīyah |
| BD | C | Dhaka |
| BD | D | Khulna |
| BD | E | Rajshahi |
| BD | G | Sylhet |
| BD | 01 | Bandarban |
| BD | 02 | Barguna |
| BD | 03 | Bogura |
| BD | 04 | Brahmanbaria |
| BD | 05 | Bagerhat |
| BD | 06 | Barishal |
| BD | 07 | Bhola |
| BD | 08 | Cumilla |
| BD | 09 | Chandpur |
| BD | 10 | Chattogram |
| BD | 11 | Cox’s Bazar |
| BD | 12 | Chuadanga |
| BD | 14 | Dinajpur |
| BD | 15 | Faridpur |
| BD | 16 | Feni |
| BD | 17 | Gopalganj |
| BD | 18 | Gazipur |
| BD | 19 | Gaibandha |
| BD | 20 | Habiganj |
| BD | 21 | Jamalpur |
| BD | 22 | Jashore |
| BD | 23 | Jhenaidah |
| BD | 24 | Joypurhat |
| BD | 25 | Jhalakathi |
| BD | 26 | Kishoreganj |
| BD | 28 | Kurigram |
| BD | 29 | Khagrachhari |
| BD | 30 | Kushtia |
| BD | 31 | Lakshmipur |
| BD | 32 | Lalmonirhat |
| BD | 33 | Manikganj |
| BD | 34 | Mymensingh |
| BD | 35 | Munshiganj |
| BD | 36 | Madaripur |
| BD | 37 | Magura |
| BD | 38 | Moulvibazar |
| BD | 39 | Meherpur |
| BD | 40 | Narayanganj |
| BD | 41 | Netrakona |
| BD | 42 | Narsingdi |
| BD | 43 | Narail |
| BD | 44 | Natore |
| BD | 45 | Chapai Nawabganj |
| BD | 46 | Nilphamari |
| BD | 47 | Noakhali |
| BD | 48 | Naogaon |
| BD | 49 | Pabna |
| BD | 50 | Pirojpur |
| BD | 51 | Patuakhali |
| BD | 52 | Panchagarh |
| BD | 53 | Rajbari |
| BD | 55 | Rangpur |
| BD | 56 | Rangamati |
| BD | 57 | Sherpur |
| BD | 58 | Satkhira |
| BD | 59 | Sirajganj |
| BD | 61 | Sunamganj |
| BD | 62 | Shariatpur |
| BD | 63 | Tangail |
| BD | 64 | Thakurgaon |
| BD | A | Barishal |
| BD | B | Chattogram |
| BD | F | Rangpur |
| BD | H | Mymensingh |
| BB | 01 | Christ Church |
| BB | 02 | Saint Andrew |
| BB | 03 | Saint George |
| BB | 04 | Saint James |
| BB | 05 | Saint John |
| BB | 06 | Saint Joseph |
| BB | 07 | Saint Lucy |
| BB | 08 | Saint Michael |
| BB | 09 | Saint Peter |
| BB | 10 | Saint Philip |
| BB | 11 | Saint Thomas |
| BY | BR | Brestskaya (Brest) |
| BY | HO | Homyel’skaya (Homyel’) |
| BY | HM | Horad Minsk |
| BY | HR | Hrodzyenskaya (Hrodna) |
| BY | MA | Mahilyowskaya (Mahilyow) |
| BY | MI | Minskaya |
| BY | VI | Vitsyebskaya (Vitsyebsk) |
| BE | VAN | Antwerpen |
| BE | WBR | Brabant Wallon |
| BE | WHT | Hainaut |
| BE | WLG | Liege |
| BE | VLI | Limburg |
| BE | WLX | Luxembourg |
| BE | WNA | Namur |
| BE | VOV | Oost-Vlaanderen |
| BE | VBR | Vlaams Brabant |
| BE | VWV | West-Vlaanderen |
| BE | BRU | “Bruxelles-Capitale, Région de” |
| BE | VLG | Vlaams Gewest |
| BE | WAL | “wallonne, Région” |
| BZ | BZ | Belize |
| BZ | CY | Cayo |
| BZ | CZL | Corozal |
| BZ | OW | Orange Walk |
| BZ | SC | Stann Creek |
| BZ | TOL | Toledo |
| BJ | AL | Alibori |
| BJ | AK | Atakora |
| BJ | AQ | Atlantique |
| BJ | BO | Borgou |
| BJ | CO | Collines |
| BJ | DO | Donga |
| BJ | KO | Kouffo |
| BJ | LI | Littoral |
| BJ | MO | Mono |
| BJ | OU | Oueme |
| BJ | PL | Plateau |
| BJ | ZO | Zou |
| BT | 33 | Bumthang |
| BT | 22 | Dagana |
| BT | GA | Gasa |
| BT | 13 | Haa |
| BT | 11 | Paro |
| BT | 23 | Punakha |
| BT | 45 | Samdrup Jongkhar |
| BT | 14 | Samtse |
| BT | 31 | Sarpang |
| BT | 15 | Thimphu |
| BT | 41 | Trashigang |
| BT | 32 | Trongsa |
| BT | 21 | Tsirang |
| BT | 24 | Wangdue Phodrang |
| BT | 34 | Zhemgang |
| BT | 12 | Chhukha |
| BT | 42 | Monggar |
| BT | 43 | Pema Gatshel |
| BT | 44 | Lhuentse |
| BT | TY | Trashi Yangtse |
| BO | H | Chuquisaca |
| BO | C | Cochabamba |
| BO | L | La Paz |
| BO | O | Oruro |
| BO | N | Pando |
| BO | P | Potosi |
| BO | S | Santa Cruz |
| BO | T | Tarija |
| BO | B | El Beni |
| BA | BIH | Federacija Bosne i Hercegovine |
| BA | BRC | Brčko distrikt |
| BA | SRP | Republika Srpska |
| BW | CE | Central |
| BW | GH | Ghanzi |
| BW | KG | Kgalagadi |
| BW | KL | Kgatleng |
| BW | KW | Kweneng |
| BW | NE | North East |
| BW | NW | North West |
| BW | SE | South East |
| BW | SO | Southern |
| BW | CH | Chobe |
| BW | FR | Francistown |
| BW | GA | Gaborone |
| BW | JW | Jwaneng |
| BW | LO | Lobatse |
| BW | SP | Selibe Phikwe |
| BW | ST | Sowa Town |
| BR | AC | Acre |
| BR | AL | Alagoas |
| BR | AP | Amapa |
| BR | AM | Amazonas |
| BR | BA | Bahia |
| BR | CE | Ceara |
| BR | DF | Distrito Federal |
| BR | ES | Espirito Santo |
| BR | GO | Goias |
| BR | MA | Maranhao |
| BR | MT | Mato Grosso |
| BR | MS | Mato Grosso do Sul |
| BR | MG | Minas Gerais |
| BR | PA | Para |
| BR | PB | Paraiba |
| BR | PR | Parana |
| BR | PE | Pernambuco |
| BR | PI | Piaui |
| BR | RN | Rio Grande do Norte |
| BR | RS | Rio Grande do Sul |
| BR | RJ | Rio de Janeiro |
| BR | RO | Rondonia |
| BR | RR | Roraima |
| BR | SC | Santa Catarina |
| BR | SP | Sao Paulo |
| BR | SE | Sergipe |
| BR | TO | Tocantins |
| BN | BE | Belait |
| BN | TE | Temburong |
| BN | TU | Tutong |
| BN | BM | Brunei-Muara |
| BG | 01 | Blagoevgrad |
| BG | 02 | Burgas |
| BG | 08 | Dobrich |
| BG | 07 | Gabrovo |
| BG | 26 | Haskovo |
| BG | 09 | Kardjali |
| BG | 10 | Kyustendil |
| BG | 11 | Lovech |
| BG | 12 | Montana |
| BG | 13 | Pazardjik |
| BG | 14 | Pernik |
| BG | 15 | Pleven |
| BG | 16 | Plovdiv |
| BG | 17 | Razgrad |
| BG | 27 | Shumen |
| BG | 19 | Silistra |
| BG | 20 | Sliven |
| BG | 21 | Smolyan |
| BG | 23 | Sofia |
| BG | 22 | Sofia - town |
| BG | 24 | Stara Zagora |
| BG | 25 | Targovishte |
| BG | 03 | Varna |
| BG | 04 | Veliko Tarnovo |
| BG | 05 | Vidin |
| BG | 06 | Vratza |
| BG | 28 | Yambol |
| BG | 18 | Ruse |
| BF | BAL | Bale |
| BF | BAM | Bam |
| BF | BAN | Banwa |
| BF | BAZ | Bazega |
| BF | BGR | Bougouriba |
| BF | BLG | Boulgou |
| BF | BLK | Boulkiemde |
| BF | COM | Comoe |
| BF | GAN | Ganzourgou |
| BF | GNA | Gnagna |
| BF | GOU | Gourma |
| BF | HOU | Houet |
| BF | IOB | Ioba |
| BF | KAD | Kadiogo |
| BF | KEN | Kenedougou |
| BF | KMD | Komondjari |
| BF | KOP | Kompienga |
| BF | KOS | Kossi |
| BF | KOP | Koulpelogo |
| BF | KOT | Kouritenga |
| BF | KOW | Kourweogo |
| BF | LER | Leraba |
| BF | LOR | Loroum |
| BF | MOU | Mouhoun |
| BF | NAO | Nahouri |
| BF | NAM | Namentenga |
| BF | NAY | Nayala |
| BF | NOU | Noumbiel |
| BF | OUB | Oubritenga |
| BF | OUD | Oudalan |
| BF | PAS | Passore |
| BF | PON | Poni |
| BF | SNG | Sanguie |
| BF | SMT | Sanmatenga |
| BF | SEN | Seno |
| BF | SIS | Sissili |
| BF | SOM | Soum |
| BF | SOR | Sourou |
| BF | TAP | Tapoa |
| BF | TUI | Tuy |
| BF | YAG | Yagha |
| BF | YAT | Yatenga |
| BF | ZIR | Ziro |
| BF | ZON | Zondoma |
| BF | ZOU | Zoundweogo |
| BF | 01 | Boucle du Mouhoun |
| BF | 02 | Cascades |
| BF | 03 | Centre |
| BF | 04 | Centre-Est |
| BF | 05 | Centre-Nord |
| BF | 06 | Centre-Ouest |
| BF | 07 | Centre-Sud |
| BF | 08 | Est |
| BF | 09 | Hauts-Bassins |
| BF | 10 | Nord |
| BF | 11 | Plateau-Central |
| BF | 12 | Sahel |
| BF | 13 | Sud-Ouest |
| BI | BB | Bubanza |
| BI | BR | Bururi |
| BI | CA | Cankuzo |
| BI | CI | Cibitoke |
| BI | GI | Gitega |
| BI | KR | Karuzi |
| BI | KY | Kayanza |
| BI | KI | Kirundo |
| BI | MA | Makamba |
| BI | MU | Muramvya |
| BI | MY | Muyinga |
| BI | MW | Mwaro |
| BI | NG | Ngozi |
| BI | RT | Rutana |
| BI | RY | Ruyigi |
| BI | BL | Bujumbura Rural |
| BI | BM | Bujumbura Mairie |
| BI | RM | Rumonge |
| KH | 1 | Banteay Meanchey |
| KH | 3 | Kampong Cham |
| KH | 4 | Kampong Chhnang |
| KH | 7 | Kampot |
| KH | 8 | Kandal |
| KH | 9 | Kaoh Kong |
| KH | 23 | Keb |
| KH | 24 | Pailin |
| KH | 12 | Phnom Penh |
| KH | 13 | Preah Vihear |
| KH | 14 | Prey Veng |
| KH | 20 | Svay Rieng |
| KH | 10 | Krâchéh |
| KH | 11 | Môndól Kiri |
| KH | 15 | Poŭthĭsăt |
| KH | 16 | Rôtânôkiri |
| KH | 17 | Siĕmréab |
| KH | 18 | Preah Sihanouk |
| KH | 19 | Stueng Traeng |
| KH | 2 | Bătdâmbâng |
| KH | 21 | Takêv |
| KH | 22 | Ŏtdâr Méan Choăy |
| KH | 25 | Tbong Khmum |
| KH | 5 | Kâmpóng Spœ |
| KH | 6 | Kâmpóng Thum |
| CM | CE | Centre |
| CM | LT | Littoral |
| CM | AD | Adamaoua |
| CM | EN | Far North |
| CM | ES | Est |
| CM | NO | North |
| CM | NW | North-West |
| CM | OU | West |
| CM | SU | Sud |
| CM | SW | Sud-Ouest |
| CV | BV | Boa Vista |
| CV | BR | Brava |
| CV | MA | Maio |
| CV | MO | Mosteiros |
| CV | PA | Paul |
| CV | PN | Porto Novo |
| CV | PR | Praia |
| CV | RG | Ribeira Grande |
| CV | SL | Sal |
| CV | CA | Santa Catarina |
| CV | CR | Santa Cruz |
| CV | SD | Sao Domingos |
| CV | SF | Sao Filipe |
| CV | SV | Sao Vicente |
| CV | TA | Tarrafal |
| CV | B | Ilhas de Barlavento |
| CV | CF | Santa Catarina do Fogo |
| CV | RB | Ribeira Brava |
| CV | RS | Ribeira Grande de Santiago |
| CV | S | Ilhas de Sotavento |
| CV | SM | São Miguel |
| CV | SO | São Lourenço dos Órgãos |
| CV | SS | São Salvador do Mundo |
| CV | TS | Tarrafal de São Nicolau |
| CF | BB | Bamingui-Bangoran |
| CF | BGF | Bangui |
| CF | BK | Basse-Kotto |
| CF | HM | Haut-Mbomou |
| CF | HK | Haute-Kotto |
| CF | LB | Lobaye |
| CF | MB | Mbomou |
| CF | NM | Nana-Mambere |
| CF | UK | Ouaka |
| CF | AC | Ouham |
| CF | OP | Ouham-Pende |
| CF | VK | Vakaga |
| CF | HS | Tö-Sangä / Mbaere-Kadeï |
| CF | KB | Gribingui |
| CF | KG | Kémo-Gribingui |
| CF | MP | Ombella-Mpoko |
| CF | SE | Sangha |
| TD | BA | Batha |
| TD | CB | Chari-Baguirmi |
| TD | GR | Guera |
| TD | KA | Kanem |
| TD | LC | Lac |
| TD | LC | Logone Occidental |
| TD | LR | Logone Oriental |
| TD | MC | Moyen-Chari |
| TD | OD | Ouaddai |
| TD | SA | Salamat |
| TD | TA | Tandjile |
| TD | BG | Bahr el Ghazal |
| TD | BO | Būrkū |
| TD | EE | Inīdī ash Sharqī |
| TD | EO | Inīdī al Gharbī |
| TD | HL | Ḩajjar Lamīs |
| TD | LO | Lūghūn al Gharbī |
| TD | MA | Māndūl |
| TD | ME | Māyū Kībbī ash Sharqī |
| TD | MO | Māyū Kībbī al Gharbī |
| TD | ND | Ville de Ndjamena |
| TD | SI | Sīlā |
| TD | TI | Tibesti |
| TD | WF | Wādī Fīrā’ |
| CL | AI | Aisen del General Carlos Ibanez |
| CL | AN | Antofagasta |
| CL | AR | Araucania |
| CL | AT | Atacama |
| CL | BI | Bio-Bio |
| CL | CO | Coquimbo |
| CL | LI | Libertador General Bernardo O’Hi |
| CL | LL | Los Lagos |
| CL | MA | Magallanes y de la Antartica Chi |
| CL | ML | Maule |
| CL | RM | Region Metropolitana |
| CL | TA | Tarapaca |
| CL | VS | Valparaiso |
| CL | AP | Arica y Parinacota |
| CL | LR | Los Ríos |
| CL | NB | Ñuble |
| CN | GX | Guangxi |
| CN | GZ | Guizhou |
| CN | HA | Hainan |
| CN | HB | Hebei |
| CN | HL | Heilongjiang |
| CN | HE | Henan |
| CN | HK | Hong Kong |
| CN | HN | Hunan |
| CN | JX | Jiangxi |
| CN | JL | Jilin |
| CN | SH | Shaanxi |
| CN | SX | Shanxi |
| CN | AH | Anhui Sheng |
| CN | BJ | Beijing Shi |
| CN | CQ | Chongqing Shi |
| CN | FJ | Fujian Sheng |
| CN | GD | Guangdong Sheng |
| CN | GS | Gansu Sheng |
| CN | HI | Hainan Sheng |
| CN | JS | Jiangsu Sheng |
| CN | LN | Liaoning Sheng |
| CN | MO | Macau SAR (see also separate country code entry under MO) |
| CN | NM | Nei Mongol Zizhiqu |
| CN | NX | Ningxia Huizi Zizhiqu |
| CN | QH | Qinghai Sheng |
| CN | SC | Sichuan Sheng |
| CN | SD | Shandong Sheng |
| CN | SN | Shaanxi Sheng |
| CN | TJ | Tianjin Shi |
| CN | TW | Taiwan Sheng (see also separate country code entry under TW) |
| CN | XJ | Xinjiang Uygur Zizhiqu |
| CN | XZ | Xizang Zizhiqu |
| CN | YN | Yunnan Sheng |
| CN | ZJ | Zhejiang Sheng |
| CO | AMA | Amazonas |
| CO | ANT | Antioquia |
| CO | ARA | Arauca |
| CO | ATL | Atlantico |
| CO | BOL | Bolivar |
| CO | BOY | Boyaca |
| CO | CAL | Caldas |
| CO | CAQ | Caqueta |
| CO | CAS | Casanare |
| CO | CAU | Cauca |
| CO | CES | Cesar |
| CO | CHO | Choco |
| CO | COR | Cordoba |
| CO | CUN | Cundinamarca |
| CO | GUA | Guainia |
| CO | GUV | Guaviare |
| CO | HUI | Huila |
| CO | MAG | Magdalena |
| CO | MET | Meta |
| CO | NAR | Narino |
| CO | NSA | Norte de Santander |
| CO | PUT | Putumayo |
| CO | QUI | Quindio |
| CO | RIS | Risaralda |
| CO | SAP | San Andres y Providencia |
| CO | SAN | Santander |
| CO | SUC | Sucre |
| CO | TOL | Tolima |
| CO | VAC | Valle del Cauca |
| CO | VAU | Vaupes |
| CO | VID | Vichada |
| CO | DC | Distrito Capital de Bogotá |
| CO | LAG | La Guajira |
| KM | A | Anjouan |
| KM | G | Grande Comore |
| KM | M | Moheli |
| CG | 11 | Bouenza |
| CG | BZV | Brazzaville |
| CG | 8 | Cuvette |
| CG | 15 | Cuvette-Ouest |
| CG | 5 | Kouilou |
| CG | 2 | Lekoumou |
| CG | 7 | Likouala |
| CG | 9 | Niari |
| CG | 14 | Plateaux |
| CG | 12 | Pool |
| CG | 13 | Sangha |
| CG | 16 | Pointe-Noire |
| CD | BC | Bas-Congo |
| CD | EQ | Equateur |
| CD | KE | Kasai-Oriental |
| CD | KN | Kinshasa |
| CD | MA | Maniema |
| CD | NK | Nord-Kivu |
| CD | SK | Sud-Kivu |
| CD | BU | Bas-Uélé |
| CD | HK | Haut-Katanga |
| CD | HL | Haut-Lomami |
| CD | HU | Haut-Uélé |
| CD | IT | Ituri |
| CD | KC | Kasaï Central |
| CD | KG | Kwango |
| CD | KL | Kwilu |
| CD | KS | Kasaï |
| CD | LO | Lomami |
| CD | LU | Lualaba |
| CD | MN | Mai-Ndombe |
| CD | MO | Mongala |
| CD | NU | Nord-Ubangi |
| CD | SA | Sankuru |
| CD | SU | Sud-Ubangi |
| CD | TA | Tanganyika |
| CD | TO | Tshopo |
| CD | TU | Tshuapa |
| CR | A | Alajuela |
| CR | C | Cartago |
| CR | G | Guanacaste |
| CR | H | Heredia |
| CR | L | Limon |
| CR | P | Puntarenas |
| CR | SJ | San Jose |
| CI | AB | Abidjan |
| CI | YM | Yamoussoukro |
| CI | BS | Bas-Sassandra |
| CI | CM | Comoé |
| CI | DN | Denguélé |
| CI | GD | Gôh-Djiboua |
| CI | LC | Lacs |
| CI | LG | Lagunes |
| CI | MG | Montagnes |
| CI | SM | Sassandra-Marahoué |
| CI | SV | Savanes |
| CI | VB | Vallée du Bandama |
| CI | WR | Woroba |
| CI | ZZ | Zanzan |
| HR | 01 | Zagrebačka županija |
| HR | 02 | Krapinsko-zagorska županija |
| HR | 03 | Sisačko-moslavačka županija |
| HR | 04 | Karlovačka županija |
| HR | 05 | Varaždinska županija |
| HR | 06 | Koprivničko-križevačka županija |
| HR | 07 | Bjelovarsko-bilogorska županija |
| HR | 08 | Primorsko-goranska županija |
| HR | 09 | Ličko-senjska županija |
| HR | 10 | Virovitičko-podravska županija |
| HR | 11 | Požeško-slavonska županija |
| HR | 12 | Brodsko-posavska županija |
| HR | 13 | Zadarska županija |
| HR | 14 | Osječko-baranjska županija |
| HR | 15 | Šibensko-kninska županija |
| HR | 16 | Vukovarsko-srijemska županija |
| HR | 17 | Splitsko-dalmatinska županija |
| HR | 18 | Istarska županija |
| HR | 19 | Dubrovačko-neretvanska županija |
| HR | 20 | Međimurska županija |
| HR | 21 | Grad Zagreb |
| CU | 09 | Camaguey |
| CU | 08 | Ciego de Avila |
| CU | 06 | Cienfuegos |
| CU | 12 | Granma |
| CU | 14 | Guantanamo |
| CU | 11 | Holguin |
| CU | 99 | Isla de la Juventud |
| CU | 03 | La Habana |
| CU | 10 | Las Tunas |
| CU | 04 | Matanzas |
| CU | 01 | Pinar del Rio |
| CU | 07 | Sancti Spiritus |
| CU | 13 | Santiago de Cuba |
| CU | 05 | Villa Clara |
| CU | 15 | Artemisa |
| CU | 16 | Mayabeque |
| CY | 01 | Lefkosia |
| CY | 02 | Leymasun |
| CY | 03 | Larnaka |
| CY | 04 | Mağusa |
| CY | 05 | Pafos |
| CY | 06 | Keryneia |
| CZ | 10 | “Praha, Hlavní město” |
| CZ | 20 | Středočeský kraj |
| CZ | 201 | Benešov |
| CZ | 202 | Beroun |
| CZ | 203 | Kladno |
| CZ | 204 | Kolín |
| CZ | 205 | Kutná Hora |
| CZ | 206 | Mělník |
| CZ | 207 | Mladá Boleslav |
| CZ | 208 | Nymburk |
| CZ | 209 | Praha-východ |
| CZ | 20A | Praha-západ |
| CZ | 20B | Příbram |
| CZ | 20C | Rakovník |
| CZ | 31 | Jihočeský kraj |
| CZ | 311 | České Budějovice |
| CZ | 312 | Český Krumlov |
| CZ | 313 | Jindřichův Hradec |
| CZ | 314 | Písek |
| CZ | 315 | Prachatice |
| CZ | 316 | Strakonice |
| CZ | 317 | Tábor |
| CZ | 32 | Plzeňský kraj |
| CZ | 321 | Domažlice |
| CZ | 322 | Klatovy |
| CZ | 323 | Plzeň-město |
| CZ | 324 | Plzeň-jih |
| CZ | 325 | Plzeň-sever |
| CZ | 326 | Rokycany |
| CZ | 327 | Tachov |
| CZ | 41 | Karlovarský kraj |
| CZ | 411 | Cheb |
| CZ | 412 | Karlovy Vary |
| CZ | 413 | Sokolov |
| CZ | 42 | Ústecký kraj |
| CZ | 421 | Děčín |
| CZ | 422 | Chomutov |
| CZ | 423 | Litoměřice |
| CZ | 424 | Louny |
| CZ | 425 | Most |
| CZ | 426 | Teplice |
| CZ | 427 | Ústí nad Labem |
| CZ | 51 | Liberecký kraj |
| CZ | 511 | Česká Lípa |
| CZ | 512 | Jablonec nad Nisou |
| CZ | 513 | Liberec |
| CZ | 514 | Semily |
| CZ | 52 | Královéhradecký kraj |
| CZ | 521 | Hradec Králové |
| CZ | 522 | Jičín |
| CZ | 523 | Náchod |
| CZ | 524 | Rychnov nad Kněžnou |
| CZ | 525 | Trutnov |
| CZ | 53 | Pardubický kraj |
| CZ | 531 | Chrudim |
| CZ | 532 | Pardubice |
| CZ | 533 | Svitavy |
| CZ | 534 | Ústí nad Orlicí |
| CZ | 63 | Kraj Vysočina |
| CZ | 631 | Havlíčkův Brod |
| CZ | 632 | Jihlava |
| CZ | 633 | Pelhřimov |
| CZ | 634 | Třebíč |
| CZ | 635 | Žďár nad Sázavou |
| CZ | 64 | Jihomoravský kraj |
| CZ | 641 | Blansko |
| CZ | 642 | Brno-město |
| CZ | 643 | Brno-venkov |
| CZ | 644 | Břeclav |
| CZ | 645 | Hodonín |
| CZ | 646 | Vyškov |
| CZ | 647 | Znojmo |
| CZ | 71 | Olomoucký kraj |
| CZ | 711 | Jeseník |
| CZ | 712 | Olomouc |
| CZ | 713 | Prostějov |
| CZ | 714 | Přerov |
| CZ | 715 | Šumperk |
| CZ | 72 | Zlínský kraj |
| CZ | 721 | Kroměříž |
| CZ | 722 | Uherské Hradiště |
| CZ | 723 | Vsetín |
| CZ | 724 | Zlín |
| CZ | 80 | Moravskoslezský kraj |
| CZ | 801 | Bruntál |
| CZ | 802 | Frýdek-Místek |
| CZ | 803 | Karviná |
| CZ | 804 | Nový Jičín |
| CZ | 805 | Opava |
| CZ | 806 | Ostrava-město |
| DK | 81 | Nordjylland |
| DK | 82 | Midtjylland |
| DK | 83 | Syddanmark |
| DK | 84 | Hovedstaden |
| DK | 85 | Sjælland |
| DJ | DI | Dikhil |
| DJ | DJ | Djibouti |
| DJ | OB | Obock |
| DJ | AR | ‘Artā |
| DJ | AS | ‘Alī Şabīḩ |
| DJ | TA | Tājūrah |
| DM | 02 | Saint Andrew |
| DM | 03 | Saint David |
| DM | 04 | Saint George |
| DM | 05 | Saint John |
| DM | 06 | Saint Joseph |
| DM | 07 | Saint Luke |
| DM | 08 | Saint Mark |
| DM | 09 | Saint Patrick |
| DM | 10 | Saint Paul |
| DM | 11 | Saint Peter |
| DO | 02 | Azua |
| DO | 03 | Baoruco |
| DO | 04 | Barahona |
| DO | 05 | Dajabon |
| DO | 06 | Duarte |
| DO | 07 | Elias Pina |
| DO | 09 | Espaillat |
| DO | 30 | Hato Mayor |
| DO | 10 | Independencia |
| DO | 11 | La Altagracia |
| DO | 12 | La Romana |
| DO | 13 | La Vega |
| DO | 14 | Maria Trinidad Sanchez |
| DO | 28 | Monsenor Nouel |
| DO | 15 | Monte Cristi |
| DO | 29 | Monte Plata |
| DO | 16 | Pedernales |
| DO | 18 | Puerto Plata |
| DO | 20 | Samana |
| DO | 21 | San Cristobal |
| DO | 31 | San Jose de Ocoa |
| DO | 22 | San Juan |
| DO | 23 | San Pedro de Macoris |
| DO | 24 | Sanchez Ramirez |
| DO | 25 | Santiago |
| DO | 26 | Santiago Rodriguez |
| DO | 32 | Santo Domingo |
| DO | 27 | Valverde |
| DO | 01 | Distrito Nacional (Santo Domingo) |
| DO | 08 | El Seibo |
| DO | 17 | Peravia |
| DO | 19 | Hermanas Mirabal |
| DO | 33 | Cibao Nordeste |
| DO | 34 | Cibao Noroeste |
| DO | 35 | Cibao Norte |
| DO | 36 | Cibao Sur |
| DO | 37 | El Valle |
| DO | 38 | Enriquillo |
| DO | 39 | Higuamo |
| DO | 40 | Ozama |
| DO | 41 | Valdesia |
| DO | 42 | Yuma |
| EC | A | Azuay |
| EC | B | Bolivar |
| EC | C | Carchi |
| EC | H | Chimborazo |
| EC | X | Cotopaxi |
| EC | O | El Oro |
| EC | E | Esmeraldas |
| EC | W | Galápagos |
| EC | G | Guayas |
| EC | I | Imbabura |
| EC | L | Loja |
| EC | R | Los Rios |
| EC | M | Manabí |
| EC | S | Morona Santiago |
| EC | N | Napo |
| EC | D | Orellana |
| EC | Y | Pastaza |
| EC | P | Pichincha |
| EC | U | Sucumbíos |
| EC | T | Tungurahua |
| EC | Z | Zamora Chinchipe |
| EC | F | Cañar |
| EC | SD | Santo Domingo de los Tsáchilas |
| EC | SE | Santa Elena |
| EG | DK | Ad Daqahliyah |
| EG | BA | Al Bahr al Ahmar |
| EG | BH | Al Buhayrah |
| EG | FYM | Al Fayyum |
| EG | GH | Al Gharbiyah |
| EG | ALX | Al Iskandariyah |
| EG | IS | Al Isma’iliyah |
| EG | GZ | Al Jizah |
| EG | MNF | Al Minufiyah |
| EG | MN | Al Minya |
| EG | C | Al Qahirah |
| EG | KB | Al Qalyubiyah |
| EG | WAD | Al Wadi al Jadid |
| EG | SUZ | As Suways |
| EG | SHR | Ash Sharqiyah |
| EG | ASN | Aswan |
| EG | AST | Asyut |
| EG | BNS | Bani Suwayf |
| EG | DT | Dumyat |
| EG | JS | Janub Sina’ |
| EG | KFS | Kafr ash Shaykh |
| EG | MT | Matruh |
| EG | KN | Qina |
| EG | SIN | Shamal Sina’ |
| EG | SHG | Suhaj |
| EG | LX | Al Uqşur |
| EG | PTS | Būr Sa‘īd |
| SV | AH | Ahuachapan |
| SV | CA | Cabanas |
| SV | CH | Chalatenango |
| SV | CU | Cuscatlan |
| SV | LI | La Libertad |
| SV | PA | La Paz |
| SV | UN | La Union |
| SV | MO | Morazan |
| SV | SM | San Miguel |
| SV | SS | San Salvador |
| SV | SV | San Vicente |
| SV | SA | Santa Ana |
| SV | SO | Sonsonate |
| SV | US | Usulutan |
| GQ | AN | Provincia Annobon |
| GQ | BN | Provincia Bioko Norte |
| GQ | BS | Provincia Bioko Sur |
| GQ | CS | Provincia Centro Sur |
| GQ | KN | Provincia Kie-Ntem |
| GQ | LI | Provincia Litoral |
| GQ | WN | Provincia Wele-Nzas |
| GQ | C | Région Continentale |
| GQ | DJ | Djibloho |
| GQ | I | Región Insular |
| ER | MA | Central (Maekel) |
| ER | SK | Northern Red Sea (Semien-Keih-Bahri) |
| ER | DK | Southern Red Sea (Debub-Keih-Bahri) |
| ER | AN | ‘Anseba |
| ER | DU | Debub |
| ER | GB | Qāsh-Barkah |
| EE | 130 | Alutaguse |
| EE | 141 | Anija |
| EE | 142 | Antsla |
| EE | 171 | Elva |
| EE | 184 | Haapsalu |
| EE | 191 | Haljala |
| EE | 198 | Harku |
| EE | 205 | Hiiumaa |
| EE | 214 | Häädemeeste |
| EE | 245 | Jõelähtme |
| EE | 247 | Jõgeva |
| EE | 251 | Jõhvi |
| EE | 255 | Järva |
| EE | 272 | Kadrina |
| EE | 283 | Kambja |
| EE | 284 | Kanepi |
| EE | 291 | Kastre |
| EE | 293 | Kehtna |
| EE | 296 | Keila |
| EE | 303 | Kihnu |
| EE | 305 | Kiili |
| EE | 317 | Kohila |
| EE | 321 | Kohtla-Järve |
| EE | 338 | Kose |
| EE | 353 | Kuusalu |
| EE | 37 | Harjumaa |
| EE | 39 | Hiiumaa |
| EE | 424 | Loksa |
| EE | 430 | Lääneranna |
| EE | 431 | Lääne-Harju |
| EE | 432 | Luunja |
| EE | 441 | Lääne-Nigula |
| EE | 442 | Lüganuse |
| EE | 446 | Maardu |
| EE | 45 | Ida-Virumaa |
| EE | 478 | Muhu |
| EE | 480 | Mulgi |
| EE | 486 | Mustvee |
| EE | 50 | Jõgevamaa |
| EE | 503 | Märjamaa |
| EE | 511 | Narva |
| EE | 514 | Narva-Jõesuu |
| EE | 52 | Järvamaa |
| EE | 528 | Nõo |
| EE | 557 | Otepää |
| EE | 56 | Läänemaa |
| EE | 567 | Paide |
| EE | 586 | Peipsiääre |
| EE | 60 | Lääne-Virumaa |
| EE | 615 | Põhja-Sakala |
| EE | 618 | Põltsamaa |
| EE | 622 | Põlva |
| EE | 624 | Pärnu |
| EE | 638 | Põhja-Pärnumaa |
| EE | 64 | Põlvamaa |
| EE | 651 | Raasiku |
| EE | 653 | Rae |
| EE | 661 | Rakvere |
| EE | 663 | Rakvere |
| EE | 668 | Rapla |
| EE | 68 | Pärnumaa |
| EE | 689 | Ruhnu |
| EE | 698 | Rõuge |
| EE | 708 | Räpina |
| EE | 71 | Raplamaa |
| EE | 712 | Saarde |
| EE | 714 | Saaremaa |
| EE | 719 | Saku |
| EE | 726 | Saue |
| EE | 732 | Setomaa |
| EE | 735 | Sillamäe |
| EE | 74 | Saaremaa |
| EE | 784 | Tallinn |
| EE | 79 | Tartumaa |
| EE | 792 | Tapa |
| EE | 793 | Tartu |
| EE | 796 | Tartu |
| EE | 803 | Toila |
| EE | 809 | Tori |
| EE | 81 | Valgamaa |
| EE | 824 | Tõrva |
| EE | 834 | Türi |
| EE | 84 | Viljandimaa |
| EE | 855 | Valga |
| EE | 87 | Võrumaa |
| EE | 890 | Viimsi |
| EE | 897 | Viljandi |
| EE | 899 | Viljandi |
| EE | 901 | Vinni |
| EE | 903 | Viru-Nigula |
| EE | 907 | Vormsi |
| EE | 917 | Võru |
| EE | 919 | Võru |
| EE | 928 | Väike-Maarja |
| ET | AA | Addis Ababa |
| ET | AF | Afar |
| ET | DD | Dire Dawa |
| ET | OR | Oromia |
| ET | SO | Somali |
| ET | SN | Southern Nations - Nationalities and Peoples Region |
| ET | TI | Tigray |
| ET | AM | Āmara |
| ET | BE | Bīnshangul Gumuz |
| ET | GA | Gambela Peoples |
| ET | HA | Hārerī Hizb |
| FJ | C | Central Division |
| FJ | E | Eastern Division |
| FJ | N | Northern Division |
| FJ | R | Rotuma |
| FJ | W | Western Division |
| FJ | 01 | Ba |
| FJ | 02 | Bua |
| FJ | 03 | Cakaudrove |
| FJ | 04 | Kadavu |
| FJ | 05 | Lau |
| FJ | 06 | Lomaiviti |
| FJ | 07 | Macuata |
| FJ | 08 | Nadroga and Navosa |
| FJ | 09 | Naitasiri |
| FJ | 10 | Namosi |
| FJ | 11 | Ra |
| FJ | 12 | Rewa |
| FJ | 13 | Serua |
| FJ | 14 | Tailevu |
| FI | 01 | Landskapet Åland |
| FI | 02 | Södra Karelen |
| FI | 03 | Södra Österbotten |
| FI | 04 | Södra Savolax |
| FI | 05 | Kajanaland |
| FI | 06 | Kanta-Häme |
| FI | 07 | Mellersta Österbotten |
| FI | 08 | Mellersta Finland |
| FI | 09 | Kymmenedalen |
| FI | 10 | Lappland |
| FI | 11 | Pirkanmaa |
| FI | 12 | Pohjanmaa |
| FI | 13 | Pohjois-Karjala |
| FI | 14 | Pohjois-Pohjanmaa |
| FI | 15 | Pohjois-Savo |
| FI | 16 | Päijät-Häme |
| FI | 17 | Satakunta |
| FI | 18 | Uusimaa |
| FI | 19 | Varsinais-Suomi |
| FR | 20R | Corse |
| FR | 01 | Ain |
| FR | 02 | Aisne |
| FR | 03 | Allier |
| FR | 04 | Alpes-de-Haute-Provence |
| FR | 05 | Hautes-Alpes |
| FR | 06 | Alpes-Maritimes |
| FR | 07 | Ardèche |
| FR | 08 | Ardennes |
| FR | 09 | Ariège |
| FR | 10 | Aube |
| FR | 11 | Aude |
| FR | 12 | Aveyron |
| FR | 13 | Bouches-du-Rhône |
| FR | 14 | Calvados |
| FR | 15 | Cantal |
| FR | 16 | Charente |
| FR | 17 | Charente-Maritime |
| FR | 18 | Cher |
| FR | 19 | Corrèze |
| FR | 21 | Côte-d’Or |
| FR | 22 | Côtes-d’Armor |
| FR | 23 | Creuse |
| FR | 24 | Dordogne |
| FR | 25 | Doubs |
| FR | 26 | Drôme |
| FR | 27 | Eure |
| FR | 28 | Eure-et-Loir |
| FR | 29 | Finistère |
| FR | 2A | Corse-du-Sud |
| FR | 2B | Haute-Corse |
| FR | 30 | Gard |
| FR | 31 | Haute-Garonne |
| FR | 32 | Gers |
| FR | 33 | Gironde |
| FR | 34 | Hérault |
| FR | 35 | Ille-et-Vilaine |
| FR | 36 | Indre |
| FR | 37 | Indre-et-Loire |
| FR | 38 | Isère |
| FR | 39 | Jura |
| FR | 40 | Landes |
| FR | 41 | Loir-et-Cher |
| FR | 42 | Loire |
| FR | 43 | Haute-Loire |
| FR | 44 | Loire-Atlantique |
| FR | 45 | Loiret |
| FR | 46 | Lot |
| FR | 47 | Lot-et-Garonne |
| FR | 48 | Lozère |
| FR | 49 | Maine-et-Loire |
| FR | 50 | Manche |
| FR | 51 | Marne |
| FR | 52 | Haute-Marne |
| FR | 53 | Mayenne |
| FR | 54 | Meurthe-et-Moselle |
| FR | 55 | Meuse |
| FR | 56 | Morbihan |
| FR | 57 | Moselle |
| FR | 58 | Nièvre |
| FR | 59 | Nord |
| FR | 60 | Oise |
| FR | 61 | Orne |
| FR | 62 | Pas-de-Calais |
| FR | 63 | Puy-de-Dôme |
| FR | 64 | Pyrénées-Atlantiques |
| FR | 65 | Hautes-Pyrénées |
| FR | 66 | Pyrénées-Orientales |
| FR | 67 | Bas-Rhin |
| FR | 68 | Haut-Rhin |
| FR | 69 | Rhône |
| FR | 70 | Haute-Saône |
| FR | 71 | Saône-et-Loire |
| FR | 72 | Sarthe |
| FR | 73 | Savoie |
| FR | 74 | Haute-Savoie |
| FR | 75 | Paris |
| FR | 76 | Seine-Maritime |
| FR | 77 | Seine-et-Marne |
| FR | 78 | Yvelines |
| FR | 79 | Deux-Sèvres |
| FR | 80 | Somme |
| FR | 81 | Tarn |
| FR | 82 | Tarn-et-Garonne |
| FR | 83 | Var |
| FR | 84 | Vaucluse |
| FR | 85 | Vendée |
| FR | 86 | Vienne |
| FR | 87 | Haute-Vienne |
| FR | 88 | Vosges |
| FR | 89 | Yonne |
| FR | 90 | Territoire de Belfort |
| FR | 91 | Essonne |
| FR | 92 | Hauts-de-Seine |
| FR | 93 | Seine-Saint-Denis |
| FR | 94 | Val-de-Marne |
| FR | 95 | Val-d’Oise |
| FR | 971 | Guadeloupe |
| FR | 972 | Martinique |
| FR | 973 | Guyane (française) |
| FR | 974 | La Réunion |
| FR | 976 | Mayotte |
| FR | ARA | Auvergne-Rhône-Alpes |
| FR | BFC | Bourgogne-Franche-Comté |
| FR | BL | Saint-Barthélemy (see also separate country code entry under BL) |
| FR | BRE | Bretagne |
| FR | CP | Clipperton |
| FR | CVL | Centre-Val de Loire |
| FR | GES | Grand-Est |
| FR | GF | Guyane (française) (see also separate country code entry under GF) |
| FR | GP | Guadeloupe (see also separate country code entry under GP) |
| FR | HDF | Hauts-de-France |
| FR | IDF | Île-de-France |
| FR | MF | Saint-Martin (see also separate country code entry under MF) |
| FR | MQ | Martinique (see also separate country code entry under MQ) |
| FR | NAQ | Nouvelle-Aquitaine |
| FR | NC | Nouvelle-Calédonie (see also separate country code entry under NC) |
| FR | NOR | Normandie |
| FR | OCC | Occitanie |
| FR | PAC | Provence-Alpes-Côte-d’Azur |
| FR | PDL | Pays-de-la-Loire |
| FR | PF | Polynésie française (see also separate country code entry under PF) |
| FR | PM | Saint-Pierre-et-Miquelon (see also separate country code entry under PM) |
| FR | RE | La Réunion (see also separate country code entry under RE) |
| FR | TF | Terres australes françaises (see also separate country code entry under TF) |
| FR | WF | Wallis-et-Futuna (see also separate country code entry under WF) |
| FR | YT | Mayotte (see also separate country code entry under YT) |
| GA | 1 | Estuaire |
| GA | 2 | Haut-Ogooue |
| GA | 3 | Moyen-Ogooue |
| GA | 4 | Ngounie |
| GA | 5 | Nyanga |
| GA | 6 | Ogooue-Ivindo |
| GA | 7 | Ogooue-Lolo |
| GA | 8 | Ogooue-Maritime |
| GA | 9 | Woleu-Ntem |
| GM | B | Banjul |
| GM | M | Central River |
| GM | L | Lower River |
| GM | N | North Bank |
| GM | U | Upper River |
| GM | W | Western |
| GE | AB | Abkhazia |
| GE | AJ | Ajaria |
| GE | GU | Guria |
| GE | IM | Imereti |
| GE | KA | Kakheti |
| GE | KK | Kvemo Kartli |
| GE | MM | Mtskheta-Mtianeti |
| GE | RL | Racha Lechkhumi and Kvemo Svanet |
| GE | SZ | Samegrelo-Zemo Svaneti |
| GE | SJ | Samtskhe-Javakheti |
| GE | SK | Shida Kartli |
| GE | TB | Tbilisi |
| DE | BY | Bayern |
| DE | BE | Berlin |
| DE | BB | Brandenburg |
| DE | HB | Bremen |
| DE | HH | Hamburg |
| DE | HE | Hessen |
| DE | MV | Mecklenburg-Vorpommern |
| DE | NI | Niedersachsen |
| DE | NW | Nordrhein-Westfalen |
| DE | RP | Rheinland-Pfalz |
| DE | RP | Rhineland-Palatinate |
| DE | SL | Saarland |
| DE | SN | Sachsen |
| DE | ST | Sachsen-Anhalt |
| DE | SH | Schleswig-Holstein |
| DE | TH | Thüringen |
| DE | BW | Baden-Württemberg |
| GH | UE | Upper East Region |
| GH | UW | Upper West Region |
| GH | AA | Greater Accra |
| GH | AF | Ahafo |
| GH | AH | Ashanti |
| GH | BE | Bono East |
| GH | BO | Bono |
| GH | CP | Central |
| GH | EP | Eastern |
| GH | NE | North East |
| GH | NP | Northern |
| GH | OT | Oti |
| GH | SV | Savannah |
| GH | TV | Volta |
| GH | WN | Western North |
| GH | WP | Western |
| GR | 69 | Ágion Óros |
| GR | A | Anatolikí Makedonía kai Thráki |
| GR | B | Kentrikí Makedonía |
| GR | C | Dytikí Makedonía |
| GR | D | Ípeiros |
| GR | E | Thessalía |
| GR | F | Ionía Nísia |
| GR | G | Dytikí Elláda |
| GR | H | Stereá Elláda |
| GR | I | Attikí |
| GR | J | Pelopónnisos |
| GR | K | Vóreio Aigaío |
| GR | L | Nótio Aigaío |
| GR | M | Kríti |
| GL | AV | Avannaata Kommunia |
| GL | KU | Kommune Kujalleq |
| GL | QE | Qeqqata Kommunia |
| GL | QT | Kommune Qeqertalik |
| GL | SM | Kommuneqarfik Sermersooq |
| GD | 01 | Saint Andrew |
| GD | 02 | Saint David |
| GD | 03 | Saint George |
| GD | 04 | Saint John |
| GD | 05 | Saint Mark |
| GD | 06 | Saint Patrick |
| GD | 10 | Southern Grenadine Islands |
| GT | AV | Alta Verapaz |
| GT | BV | Baja Verapaz |
| GT | CM | Chimaltenango |
| GT | CQ | Chiquimula |
| GT | PE | El Peten |
| GT | PR | El Progreso |
| GT | QC | El Quiche |
| GT | ES | Escuintla |
| GT | GU | Guatemala |
| GT | HU | Huehuetenango |
| GT | IZ | Izabal |
| GT | JA | Jalapa |
| GT | JU | Jutiapa |
| GT | QZ | Quetzaltenango |
| GT | RE | Retalhuleu |
| GT | SA | Sacatepequez |
| GT | SM | San Marcos |
| GT | SR | Santa Rosa |
| GT | SO | Solola |
| GT | SU | Suchitepequez |
| GT | TO | Totonicapan |
| GT | ZA | Zacapa |
| GN | BE | Beyla |
| GN | BF | Boffa |
| GN | B | Boke |
| GN | C | Conakry |
| GN | CO | Coyah |
| GN | DB | Dabola |
| GN | DL | Dalaba |
| GN | DI | Dinguiraye |
| GN | DU | Dubreka |
| GN | F | Faranah |
| GN | FO | Forecariah |
| GN | FR | Fria |
| GN | GA | Gaoual |
| GN | K | Kankan |
| GN | KE | Kerouane |
| GN | D | Kindia |
| GN | KS | Kissidougou |
| GN | KB | Koubia |
| GN | KN | Koundara |
| GN | KO | Kouroussa |
| GN | L | Labe |
| GN | LE | Lelouma |
| GN | LO | Lola |
| GN | MC | Macenta |
| GN | ML | Mali |
| GN | M | Mamou |
| GN | MD | Mandiana |
| GN | N | Nzerekore |
| GN | PI | Pita |
| GN | SI | Siguiri |
| GN | TE | Telimele |
| GN | TO | Tougue |
| GN | YO | Yomou |
| GN | GU | Guékédou |
| GW | BS | Bissau Region |
| GW | BL | Bolama Region |
| GW | CA | Cacheu Region |
| GW | GA | Gabu Region |
| GW | OI | Oio Region |
| GW | QU | Quinara Region |
| GW | TO | Tombali Region |
| GW | BA | Bafatá |
| GW | BM | Biombo |
| GW | L | Leste |
| GW | N | Norte |
| GW | S | Sul |
| GY | BA | Barima-Waini |
| GY | CU | Cuyuni-Mazaruni |
| GY | DE | Demerara-Mahaica |
| GY | EB | East Berbice-Corentyne |
| GY | ES | Essequibo Islands-West Demerara |
| GY | MA | Mahaica-Berbice |
| GY | PM | Pomeroon-Supenaam |
| GY | PT | Potaro-Siparuni |
| GY | UD | Upper Demerara-Berbice |
| GY | UT | Upper Takutu-Upper Essequibo |
| HT | AR | Artibonite |
| HT | CE | Centre |
| HT | GA | Grand’Anse |
| HT | ND | Nord |
| HT | NE | Nord-Est |
| HT | NO | Nord-Ouest |
| HT | OU | Ouest |
| HT | SD | Sud |
| HT | SE | Sud-Est |
| HT | NI | Nippes |
| HN | AT | Atlantida |
| HN | CH | Choluteca |
| HN | CL | Colon |
| HN | CM | Comayagua |
| HN | CP | Copan |
| HN | CR | Cortes |
| HN | EP | El Paraiso |
| HN | FM | Francisco Morazan |
| HN | GD | Gracias a Dios |
| HN | IN | Intibuca |
| HN | IB | Islas de la Bahia (Bay Islands) |
| HN | LP | La Paz |
| HN | LE | Lempira |
| HN | OC | Ocotepeque |
| HN | OL | Olancho |
| HN | SB | Santa Barbara |
| HN | VA | Valle |
| HN | YO | Yoro |
| HU | BK | Bacs-Kiskun |
| HU | BA | Baranya |
| HU | BE | Bekes |
| HU | BC | Bekescsaba |
| HU | BZ | Borsod-Abauj-Zemplen |
| HU | BU | Budapest |
| HU | CS | Csongrad |
| HU | DE | Debrecen |
| HU | DU | Dunaujvaros |
| HU | EG | Eger |
| HU | FE | Fejer |
| HU | GY | Gyor |
| HU | GS | Gyor-Moson-Sopron |
| HU | HB | Hajdu-Bihar |
| HU | HE | Heves |
| HU | HV | Hodmezovasarhely |
| HU | JN | Jasz-Nagykun-Szolnok |
| HU | KV | Kaposvar |
| HU | KM | Kecskemet |
| HU | KE | Komarom-Esztergom |
| HU | MI | Miskolc |
| HU | NK | Nagykanizsa |
| HU | NO | Nograd |
| HU | NY | Nyiregyhaza |
| HU | PE | Pecs |
| HU | PE | Pest |
| HU | SO | Somogy |
| HU | SN | Sopron |
| HU | SZ | Szabolcs-Szatmar-Bereg |
| HU | SZ | Szeged |
| HU | SF | Szekesfehervar |
| HU | SK | Szolnok |
| HU | SH | Szombathely |
| HU | TB | Tatabanya |
| HU | TO | Tolna |
| HU | VA | Vas |
| HU | VE | Veszprem |
| HU | ZA | Zala |
| HU | ZE | Zalaegerszeg |
| HU | ER | Érd |
| HU | ST | Salgótarján |
| IS | 7 | Austurland |
| IS | 3 | Vesturland |
| IS | 1 | Höfuðborgarsvæði |
| IS | 2 | Suðurnes |
| IS | 4 | Vestfirðir |
| IS | 5 | Norðurland vestra |
| IS | 6 | Norðurland eystra |
| IS | 8 | Suðurland |
| IS | AKH | Akrahreppur |
| IS | AKN | Akraneskaupstaður |
| IS | AKU | Akureyrarbær |
| IS | ARN | Árneshreppur |
| IS | ASA | Ásahreppur |
| IS | BFJ | Borgarfjarðarhreppur |
| IS | BLA | Bláskógabyggð |
| IS | BLO | Blönduósbær |
| IS | BOG | Borgarbyggð |
| IS | BOL | Bolungarvíkurkaupstaður |
| IS | DAB | Dalabyggð |
| IS | DAV | Dalvíkurbyggð |
| IS | DJU | Djúpavogshreppur |
| IS | EOM | Eyja- og Miklaholtshreppur |
| IS | EYF | Eyjafjarðarsveit |
| IS | FJD | Fjarðabyggð |
| IS | FJL | Fjallabyggð |
| IS | FLA | Flóahreppur |
| IS | FLD | Fljótsdalshérað |
| IS | FLR | Fljótsdalshreppur |
| IS | GAR | Garðabær |
| IS | GOG | Grímsnes- og Grafningshreppur |
| IS | GRN | Grindavíkurbær |
| IS | GRU | Grundarfjarðarbær |
| IS | GRY | Grýtubakkahreppur |
| IS | HAF | Hafnarfjarðarkaupstaður |
| IS | HEL | Helgafellssveit |
| IS | HRG | Hörgársveit |
| IS | HRU | Hrunamannahreppur |
| IS | HUT | Húnavatnshreppur |
| IS | HUV | Húnaþing vestra |
| IS | HVA | Hvalfjarðarsveit |
| IS | HVE | Hveragerðisbær |
| IS | ISA | Ísafjarðarbær |
| IS | KAL | Kaldrananeshreppur |
| IS | KJO | Kjósarhreppur |
| IS | KOP | Kópavogsbær |
| IS | LAN | Langanesbyggð |
| IS | MOS | Mosfellsbær |
| IS | MYR | Mýrdalshreppur |
| IS | NOR | Norðurþing |
| IS | RGE | Rangárþing eystra |
| IS | RGY | Rangárþing ytra |
| IS | RHH | Reykhólahreppur |
| IS | RKN | Reykjanesbær |
| IS | RKV | Reykjavíkurborg |
| IS | SBH | Svalbarðshreppur |
| IS | SBT | Svalbarðsstrandarhreppur |
| IS | SDN | Suðurnesjabær |
| IS | SDV | Súðavíkurhreppur |
| IS | SEL | Seltjarnarnesbær |
| IS | SEY | Seyðisfjarðarkaupstaður |
| IS | SFA | Sveitarfélagið Árborg |
| IS | SHF | Sveitarfélagið Hornafjörður |
| IS | SKF | Skaftárhreppur |
| IS | SKG | Skagabyggð |
| IS | SKO | Skorradalshreppur |
| IS | SKU | Skútustaðahreppur |
| IS | SNF | Snæfellsbær |
| IS | SOG | Skeiða- og Gnúpverjahreppur |
| IS | SOL | Sveitarfélagið Ölfus |
| IS | SSF | Sveitarfélagið Skagafjörður |
| IS | SSS | Sveitarfélagið Skagaströnd |
| IS | STR | Strandabyggð |
| IS | STY | Stykkishólmsbær |
| IS | SVG | Sveitarfélagið Vogar |
| IS | TAL | Tálknafjarðarhreppur |
| IS | THG | Þingeyjarsveit |
| IS | TJO | Tjörneshreppur |
| IS | VEM | Vestmannaeyjabær |
| IS | VER | Vesturbyggð |
| IS | VOP | Vopnafjarðarhreppur |
| IN | AN | Andaman and Nicobar Islands |
| IN | AP | Andhra Pradesh |
| IN | AR | Arunāchal Pradesh |
| IN | AS | Assam |
| IN | CH | Chandīgarh |
| IN | CT | Chhattīsgarh |
| IN | DH | Dādra and Nagar Haveli and Damān and Diu |
| IN | GA | Goa |
| IN | HP | Himāchal Pradesh |
| IN | HR | Haryāna |
| IN | JH | Jhārkhand |
| IN | JK | Jammu and Kashmīr |
| IN | KL | Kerala |
| IN | LA | Ladākh |
| IN | LD | Lakshadweep |
| IN | MH | Mahārāshtra |
| IN | ML | Meghālaya |
| IN | MN | Manipur |
| IN | MP | Madhya Pradesh |
| IN | MZ | Mizoram |
| IN | NL | Nāgāland |
| IN | OR | Odisha |
| IN | PB | Punjab |
| IN | PY | Puducherry |
| IN | RJ | Rājasthān |
| IN | TG | Telangāna |
| IN | TN | Tamil Nādu |
| IN | UP | Uttar Pradesh |
| IN | UT | Uttarākhand |
| IN | WB | West Bengal |
| ID | AC | Aceh |
| ID | BA | Bali |
| ID | BT | Banten |
| ID | BE | Bengkulu |
| ID | GO | Gorontalo |
| ID | JK | Jakarta Raya |
| ID | JA | Jambi |
| ID | JB | Jawa Barat |
| ID | JT | Jawa Tengah |
| ID | JI | Jawa Timur |
| ID | KB | Kalimantan Barat |
| ID | KS | Kalimantan Selatan |
| ID | KT | Kalimantan Tengah |
| ID | KI | Kalimantan Timur |
| ID | BB | Kepulauan Bangka Belitung |
| ID | LA | Lampung |
| ID | ML | Maluku |
| ID | MU | Maluku Utara |
| ID | NB | Nusa Tenggara Barat |
| ID | NT | Nusa Tenggara Timur |
| ID | PP | Papua |
| ID | RI | Riau |
| ID | SN | Sulawesi Selatan |
| ID | ST | Sulawesi Tengah |
| ID | SG | Sulawesi Tenggara |
| ID | SA | Sulawesi Utara |
| ID | SB | Sumatera Barat |
| ID | SS | Sumatera Selatan |
| ID | SU | Sumatera Utara |
| ID | YO | Yogyakarta |
| ID | JW | Jawa |
| ID | KA | Kalimantan |
| ID | KR | Kepulauan Riau |
| ID | KU | Kalimantan Utara |
| ID | NU | Nusa Tenggara |
| ID | PB | Papua Barat |
| ID | SL | Sulawesi |
| ID | SM | Sumatera |
| ID | SR | Sulawesi Barat |
| IR | 24 | Ardabil |
| IR | 18 | Bushehr |
| IR | 10 | Esfahan |
| IR | 07 | Fars |
| IR | 01 | Gilan |
| IR | 27 | Golestan |
| IR | 13 | Hamadan |
| IR | 22 | Hormozgan |
| IR | 16 | Ilam |
| IR | 08 | Kerman |
| IR | 05 | Kermanshah |
| IR | 06 | Khuzestan |
| IR | 15 | Lorestan |
| IR | 00 | Markazi |
| IR | 02 | Mazandaran |
| IR | 26 | Qazvin |
| IR | 25 | Qom |
| IR | 20 | Semnan |
| IR | 23 | Tehran |
| IR | 21 | Yazd |
| IR | 19 | Zanjan |
| IR | 03 | Āz̄ārbāyjān-e Shārqī |
| IR | 04 | Āz̄ārbāyjān-e Ghārbī |
| IR | 09 | Khorāsān-e Raẕavī |
| IR | 11 | Sīstān va Balūchestān |
| IR | 12 | Kordestān |
| IR | 14 | Chahār Maḩāl va Bakhtīārī |
| IR | 17 | Kohgīlūyeh va Bowyer Aḩmad |
| IR | 28 | Khorāsān-e Shomālī |
| IR | 29 | Khorāsān-e Jonūbī |
| IR | 30 | Alborz |
| IQ | AN | Al Anbar |
| IQ | BA | Al Basrah |
| IQ | MU | Al Muthanna |
| IQ | QA | Al Qadisyah |
| IQ | NA | An Najaf |
| IQ | AR | Arbil |
| IQ | SU | As Sulaymaniyah |
| IQ | BB | Babil |
| IQ | BG | Baghdad |
| IQ | DA | Dahuk |
| IQ | DQ | Dhi Qar |
| IQ | DI | Diyala |
| IQ | MA | Maysan |
| IQ | NI | Ninawa |
| IQ | SD | Salah ad Din |
| IQ | WA | Wasit |
| IQ | KA | Karbalā’ |
| IQ | KI | Kirkūk |
| IE | CW | Carlow |
| IE | CN | Cavan |
| IE | CE | Clare |
| IE | CO | Cork |
| IE | DL | Donegal |
| IE | D | Dublin |
| IE | G | Galway |
| IE | KE | Kerry |
| IE | KE | Kildare |
| IE | KK | Kilkenny |
| IE | LS | Laois |
| IE | LM | Leitrim |
| IE | LK | Limerick |
| IE | LD | Longford |
| IE | LH | Louth |
| IE | MO | Mayo |
| IE | MH | Meath |
| IE | MO | Monaghan |
| IE | OY | Offaly |
| IE | RN | Roscommon |
| IE | SO | Sligo |
| IE | TA | Tipperary |
| IE | WD | Waterford |
| IE | WH | Westmeath |
| IE | WX | Wexford |
| IE | WW | Wicklow |
| IE | C | Connaught |
| IE | L | Leinster |
| IE | M | Munster |
| IE | U | Ulster |
| IL | HA | Haifa |
| IL | JM | Jehuda Mountains |
| IL | TA | Tel Aviv (Gosh Dan) |
| IL | D | Ha Darom |
| IL | M | Ha Merkaz |
| IL | Z | Ha Tsafon |
| IT | AG | Agrigento |
| IT | AL | Alessandria |
| IT | AN | Ancona |
| IT | AR | Arezzo |
| IT | AP | Ascoli Piceno |
| IT | AT | Asti |
| IT | AV | Avellino |
| IT | BA | Bari |
| IT | BL | Belluno |
| IT | BN | Benevento |
| IT | BG | Bergamo |
| IT | BI | Biella |
| IT | BO | Bologna |
| IT | BZ | Bolzano |
| IT | BS | Brescia |
| IT | BR | Brindisi |
| IT | CA | Cagliari |
| IT | CL | Caltanissetta |
| IT | CB | Campobasso |
| IT | CE | Caserta |
| IT | CT | Catania |
| IT | CZ | Catanzaro |
| IT | CH | Chieti |
| IT | CO | Como |
| IT | CS | Cosenza |
| IT | CR | Cremona |
| IT | KR | Crotone |
| IT | CN | Cuneo |
| IT | EN | Enna |
| IT | FE | Ferrara |
| IT | FI | Firenze |
| IT | FG | Foggia |
| IT | FC | Forli-Cesena |
| IT | FR | Frosinone |
| IT | GE | Genova |
| IT | GO | Gorizia |
| IT | GR | Grosseto |
| IT | IM | Imperia |
| IT | IS | Isernia |
| IT | AQ | L’Aquila |
| IT | SP | La Spezia |
| IT | LT | Latina |
| IT | LE | Lecce |
| IT | LC | Lecco |
| IT | LI | Livorno |
| IT | LO | Lodi |
| IT | LU | Lucca |
| IT | MC | Macerata |
| IT | MN | Mantova |
| IT | MS | Massa-Carrara |
| IT | MT | Matera |
| IT | ME | Messina |
| IT | MI | Milano |
| IT | MO | Modena |
| IT | NA | Napoli |
| IT | NO | Novara |
| IT | NU | Nuoro |
| IT | OR | Oristano |
| IT | PD | Padova |
| IT | PA | Palermo |
| IT | PR | Parma |
| IT | PV | Pavia |
| IT | PG | Perugia |
| IT | PU | Pesaro e Urbino |
| IT | PE | Pescara |
| IT | PC | Piacenza |
| IT | PI | Pisa |
| IT | PT | Pistoia |
| IT | PN | Pordenone |
| IT | PZ | Potenza |
| IT | PO | Prato |
| IT | RG | Ragusa |
| IT | RA | Ravenna |
| IT | RC | Reggio Calabria |
| IT | RE | Reggio Emilia |
| IT | RI | Rieti |
| IT | RN | Rimini |
| IT | RM | Roma |
| IT | RO | Rovigo |
| IT | SA | Salerno |
| IT | SS | Sassari |
| IT | SV | Savona |
| IT | SI | Siena |
| IT | SR | Siracusa |
| IT | SO | Sondrio |
| IT | TA | Taranto |
| IT | TE | Teramo |
| IT | TR | Terni |
| IT | TO | Torino |
| IT | TP | Trapani |
| IT | TN | Trento |
| IT | TV | Treviso |
| IT | TS | Trieste |
| IT | UD | Udine |
| IT | VA | Varese |
| IT | VE | Venezia |
| IT | VB | Verbano-Cusio-Ossola |
| IT | VC | Vercelli |
| IT | VR | Verona |
| IT | VV | Vibo Valentia |
| IT | VI | Vicenza |
| IT | VT | Viterbo |
| IT | 21 | Piemonte |
| IT | 23 | Valle d’Aosta |
| IT | 25 | Lombardia |
| IT | 32 | Trentino-Südtirol |
| IT | 34 | Veneto |
| IT | 36 | Friuli Venezia Giulia |
| IT | 42 | Liguria |
| IT | 45 | Emilia-Romagna |
| IT | 52 | Toscana |
| IT | 55 | Umbria |
| IT | 57 | Marche |
| IT | 62 | Lazio |
| IT | 65 | Abruzzo |
| IT | 67 | Molise |
| IT | 72 | Campania |
| IT | 75 | Puglia |
| IT | 77 | Basilicata |
| IT | 78 | Calabria |
| IT | 82 | Sicilia |
| IT | 88 | Sardegna |
| IT | BT | Barletta-Andria-Trani |
| IT | FM | Fermo |
| IT | MB | Monza e Brianza |
| IT | SU | Sud Sardegna |
| JM | 01 | Kingston |
| JM | 02 | Saint Andrew |
| JM | 03 | Saint Thomas |
| JM | 04 | Portland |
| JM | 05 | Saint Mary |
| JM | 06 | Saint Ann |
| JM | 07 | Trelawny |
| JM | 08 | Saint James |
| JM | 09 | Hanover |
| JM | 10 | Westmoreland |
| JM | 11 | Saint Elizabeth |
| JM | 12 | Manchester |
| JM | 13 | Clarendon |
| JM | 14 | Saint Catherine |
| JP | 23 | Aichi |
| JP | 05 | Akita |
| JP | 02 | Aomori |
| JP | 12 | Chiba |
| JP | 38 | Ehime |
| JP | 18 | Fukui |
| JP | 40 | Fukuoka |
| JP | 07 | Fukushima |
| JP | 21 | Gifu |
| JP | 34 | Hiroshima |
| JP | 01 | Hokkaido |
| JP | 28 | Hyogo |
| JP | 08 | Ibaraki |
| JP | 17 | Ishikawa |
| JP | 03 | Iwate |
| JP | 37 | Kagawa |
| JP | 46 | Kagoshima |
| JP | 14 | Kanagawa |
| JP | 39 | Kochi |
| JP | 43 | Kumamoto |
| JP | 26 | Kyoto |
| JP | 24 | Mie |
| JP | 04 | Miyagi |
| JP | 45 | Miyazaki |
| JP | 20 | Nagano |
| JP | 42 | Nagasaki |
| JP | 29 | Nara |
| JP | 15 | Niigata |
| JP | 44 | Oita |
| JP | 33 | Okayama |
| JP | 47 | Okinawa |
| JP | 27 | Osaka |
| JP | 41 | Saga |
| JP | 11 | Saitama |
| JP | 25 | Shiga |
| JP | 32 | Shimane |
| JP | 22 | Shizuoka |
| JP | 09 | Tochigi |
| JP | 36 | Tokushima |
| JP | 13 | Tokyo |
| JP | 31 | Tottori |
| JP | 16 | Toyama |
| JP | 30 | Wakayama |
| JP | 06 | Yamagata |
| JP | 35 | Yamaguchi |
| JP | 19 | Yamanashi |
| JP | 10 | Gunma |
| JO | AM | ‘Amman |
| JO | AJ | Ajlun |
| JO | KA | Al Karak |
| JO | MA | Al Mafraq |
| JO | AT | At Tafilah |
| JO | AZ | Az Zarqa’ |
| JO | IR | Irbid |
| JO | JA | Jarash |
| JO | MA | Ma’an |
| JO | MD | Madaba |
| JO | AQ | Al ‘Aqabah |
| JO | BA | Al Balqā’ |
| JO | MN | Ma‘ān |
| KZ | ALA | Almaty |
| KZ | AKM | Aqmola oblysy |
| KZ | AKT | Aqtöbe oblysy |
| KZ | ALM | Almaty oblysy |
| KZ | AST | Nur-Sultan |
| KZ | ATY | Atyrauskaya oblast’ |
| KZ | KAR | Qaraghandy oblysy |
| KZ | KUS | Qostanay oblysy |
| KZ | KZY | Qyzylorda oblysy |
| KZ | MAN | Mangystauskaja oblast’ |
| KZ | PAV | Pavlodarskaya oblast’ |
| KZ | SEV | Soltüstik Qazaqstan oblysy |
| KZ | SHY | Šimkent |
| KZ | VOS | Vostočno-Kazahstanskaja oblast’ |
| KZ | YUZ | Türkistan oblysy |
| KZ | ZAP | Zapadno-Kazakhstanskaya oblast’ |
| KZ | ZHA | Zhambylskaya oblast’ |
| KE | 01 | Baringo |
| KE | 02 | Bomet |
| KE | 03 | Bungoma |
| KE | 04 | Busia |
| KE | 05 | Elgeyo/Marakwet |
| KE | 06 | Embu |
| KE | 07 | Garissa |
| KE | 08 | Homa Bay |
| KE | 09 | Isiolo |
| KE | 10 | Kajiado |
| KE | 11 | Kakamega |
| KE | 12 | Kericho |
| KE | 13 | Kiambu |
| KE | 14 | Kilifi |
| KE | 15 | Kirinyaga |
| KE | 16 | Kisii |
| KE | 17 | Kisumu |
| KE | 18 | Kitui |
| KE | 19 | Kwale |
| KE | 20 | Laikipia |
| KE | 21 | Lamu |
| KE | 22 | Machakos |
| KE | 23 | Makueni |
| KE | 24 | Mandera |
| KE | 25 | Marsabit |
| KE | 26 | Meru |
| KE | 27 | Migori |
| KE | 28 | Mombasa |
| KE | 29 | Murang’a |
| KE | 30 | Nairobi City |
| KE | 31 | Nakuru |
| KE | 32 | Nandi |
| KE | 33 | Narok |
| KE | 34 | Nyamira |
| KE | 35 | Nyandarua |
| KE | 36 | Nyeri |
| KE | 37 | Samburu |
| KE | 38 | Siaya |
| KE | 39 | Taita/Taveta |
| KE | 40 | Tana River |
| KE | 41 | Tharaka-Nithi |
| KE | 42 | Trans Nzoia |
| KE | 43 | Turkana |
| KE | 44 | Uasin Gishu |
| KE | 45 | Vihiga |
| KE | 46 | Wajir |
| KE | 47 | West Pokot |
| KI | G | Gilbert Islands |
| KI | L | Line Islands |
| KI | P | Phoenix Islands |
| KP | 04 | Chagang-do |
| KP | 09 | Hamgyong-bukto |
| KP | 08 | Hamgyong-namdo |
| KP | 06 | Hwanghae-bukto |
| KP | 05 | Hwanghae-namdo |
| KP | 07 | Kangwon-do |
| KP | 03 | P’yongan-bukto |
| KP | 02 | P’yongan-namdo |
| KP | 01 | Phyeongyang |
| KP | 10 | Ryangkangto |
| KP | 13 | Rasǒn |
| KP | 14 | Namp’o |
| KR | 11 | Seoul-teukbyeolsi |
| KR | 26 | Busan-gwangyeoksi |
| KR | 27 | Daegu-gwangyeoksi |
| KR | 28 | Incheon-gwangyeoksi |
| KR | 29 | Gwangju-gwangyeoksi |
| KR | 30 | Daejeon-gwangyeoksi |
| KR | 31 | Ulsan-gwangyeoksi |
| KR | 41 | Gyeonggi-do |
| KR | 42 | Gangwon-do |
| KR | 43 | Chungcheongbuk-do |
| KR | 44 | Chungcheongnam-do |
| KR | 45 | Jeollabuk-do |
| KR | 46 | Jeollanam-do |
| KR | 47 | Gyeongsangbuk-do |
| KR | 48 | Gyeongsangnam-do |
| KR | 49 | Jeju-teukbyeoljachido |
| KR | 50 | Sejong |
| KW | AH | Al Ahmadi |
| KW | FA | Al Farwaniyah |
| KW | HA | Hawalli |
| KW | JA | Al Jahrā’ |
| KW | KU | Al ‘Āşimah |
| KW | MU | Mubārak al Kabīr |
| KG | B | Batken |
| KG | GB | Bishkek |
| KG | C | Chu |
| KG | J | Jalal-Abad |
| KG | N | Naryn |
| KG | O | Osh |
| KG | T | Talas |
| KG | Y | Ysyk-Kol |
| KG | GO | Osh Shaary |
| LA | AT | Attapu |
| LA | BK | Bokeo |
| LA | BL | Bolikhamxai |
| LA | CH | Champasak |
| LA | HO | Houaphan |
| LA | KH | Khammouan |
| LA | LM | Louang Namtha |
| LA | LP | Louangphabang |
| LA | OU | Oudomxai |
| LA | PH | Phongsali |
| LA | SL | Salavan |
| LA | SV | Savannakhet |
| LA | VT | Vientiane |
| LA | XA | Xaignabouli |
| LA | XS | Xaisomboun |
| LA | XE | Xekong |
| LA | XI | Xiangkhoang |
| LV | DGV | Daugavpils |
| LV | JEL | Jelgava |
| LV | JUR | Jurmala |
| LV | LPX | Liepaja |
| LV | REZ | Rezekne |
| LV | RIX | Riga |
| LV | VEN | Ventspils |
| LV | 001 | Aglonas novads |
| LV | 002 | Aizkraukles novads |
| LV | 003 | Aizputes novads |
| LV | 004 | Aknīstes novads |
| LV | 005 | Alojas novads |
| LV | 006 | Alsungas novads |
| LV | 007 | Alūksnes novads |
| LV | 008 | Amatas novads |
| LV | 009 | Apes novads |
| LV | 010 | Auces novads |
| LV | 011 | Ādažu novads |
| LV | 012 | Babītes novads |
| LV | 013 | Baldones novads |
| LV | 014 | Baltinavas novads |
| LV | 015 | Balvu novads |
| LV | 016 | Bauskas novads |
| LV | 017 | Beverīnas novads |
| LV | 018 | Brocēnu novads |
| LV | 019 | Burtnieku novads |
| LV | 020 | Carnikavas novads |
| LV | 021 | Cesvaines novads |
| LV | 022 | Cēsu novads |
| LV | 023 | Ciblas novads |
| LV | 024 | Dagdas novads |
| LV | 025 | Daugavpils novads |
| LV | 026 | Dobeles novads |
| LV | 027 | Dundagas novads |
| LV | 028 | Durbes novads |
| LV | 029 | Engures novads |
| LV | 030 | Ērgļu novads |
| LV | 031 | Garkalnes novads |
| LV | 032 | Grobiņas novads |
| LV | 033 | Gulbenes novads |
| LV | 034 | Iecavas novads |
| LV | 035 | Ikšķiles novads |
| LV | 036 | Ilūkstes novads |
| LV | 037 | Inčukalna novads |
| LV | 038 | Jaunjelgavas novads |
| LV | 039 | Jaunpiebalgas novads |
| LV | 040 | Jaunpils novads |
| LV | 041 | Jelgavas novads |
| LV | 042 | Jēkabpils novads |
| LV | 043 | Kandavas novads |
| LV | 044 | Kārsavas novads |
| LV | 045 | Kocēnu novads |
| LV | 046 | Kokneses novads |
| LV | 047 | Krāslavas novads |
| LV | 048 | Krimuldas novads |
| LV | 049 | Krustpils novads |
| LV | 050 | Kuldīgas novads |
| LV | 051 | Ķeguma novads |
| LV | 052 | Ķekavas novads |
| LV | 053 | Lielvārdes novads |
| LV | 054 | Limbažu novads |
| LV | 055 | Līgatnes novads |
| LV | 056 | Līvānu novads |
| LV | 057 | Lubānas novads |
| LV | 058 | Ludzas novads |
| LV | 059 | Madonas novads |
| LV | 060 | Mazsalacas novads |
| LV | 061 | Mālpils novads |
| LV | 062 | Mārupes novads |
| LV | 063 | Mērsraga novads |
| LV | 064 | Naukšēnu novads |
| LV | 065 | Neretas novads |
| LV | 066 | Nīcas novads |
| LV | 067 | Ogres novads |
| LV | 068 | Olaines novads |
| LV | 069 | Ozolnieku novads |
| LV | 070 | Pārgaujas novads |
| LV | 071 | Pāvilostas novads |
| LV | 072 | Pļaviņu novads |
| LV | 073 | Preiļu novads |
| LV | 074 | Priekules novads |
| LV | 075 | Priekuļu novads |
| LV | 076 | Raunas novads |
| LV | 077 | Rēzeknes novads |
| LV | 078 | Riebiņu novads |
| LV | 079 | Rojas novads |
| LV | 080 | Ropažu novads |
| LV | 081 | Rucavas novads |
| LV | 082 | Rugāju novads |
| LV | 083 | Rundāles novads |
| LV | 084 | Rūjienas novads |
| LV | 085 | Salas novads |
| LV | 086 | Salacgrīvas novads |
| LV | 087 | Salaspils novads |
| LV | 088 | Saldus novads |
| LV | 089 | Saulkrastu novads |
| LV | 090 | Sējas novads |
| LV | 091 | Siguldas novads |
| LV | 092 | Skrīveru novads |
| LV | 093 | Skrundas novads |
| LV | 094 | Smiltenes novads |
| LV | 095 | Stopiņu novads |
| LV | 096 | Strenču novads |
| LV | 097 | Talsu novads |
| LV | 098 | Tērvetes novads |
| LV | 099 | Tukuma novads |
| LV | 100 | Vaiņodes novads |
| LV | 101 | Valkas novads |
| LV | 102 | Varakļānu novads |
| LV | 103 | Vārkavas novads |
| LV | 104 | Vecpiebalgas novads |
| LV | 105 | Vecumnieku novads |
| LV | 106 | Ventspils novads |
| LV | 107 | Viesītes novads |
| LV | 108 | Viļakas novads |
| LV | 109 | Viļānu novads |
| LV | 110 | Zilupes novads |
| LV | JKB | Jēkabpils |
| LV | VMR | Valmiera |
| LB | AK | Aakkâr |
| LB | BI | Al Biqā‘ |
| LB | JA | Al Janūb |
| LB | NA | An Nabaţīyah |
| LB | AS | Ash Shimāl |
| LB | BH | Baalbek-Hermel |
| LB | BA | Beyrouth |
| LB | BI | Béqaa |
| LB | BH | B‘alabak-Al Hirmil |
| LB | JL | Jabal Lubnān |
| LB | AS | Liban-Nord |
| LB | JA | Liban-Sud |
| LB | JL | Mont-Liban |
| LB | NA | Nabatîyé |
| LS | D | Berea |
| LS | C | Leribe |
| LS | E | Mafeteng |
| LS | A | Maseru |
| LS | F | Mohale’s Hoek |
| LS | J | Mokhotlong |
| LS | H | Qacha’s Nek |
| LS | G | Quthing |
| LS | K | Thaba-Tseka |
| LS | B | Botha-Bothe |
| LR | BM | Bomi |
| LR | BG | Bong |
| LR | GB | Grand Bassa |
| LR | CM | Grand Cape Mount |
| LR | GG | Grand Gedeh |
| LR | GK | Grand Kru |
| LR | LO | Lofa |
| LR | MG | Margibi |
| LR | MY | Maryland |
| LR | MO | Montserrado |
| LR | NI | Nimba |
| LR | RI | River Cess |
| LR | SI | Sinoe |
| LR | GP | Gbarpolu |
| LR | RG | River Gee |
| LY | JA | Al Jabal al Akhdar |
| LY | JU | Al Jufrah |
| LY | KF | Al Kufrah |
| LY | NQ | An Nuqat al Khams |
| LY | ZA | Az Zawiyah |
| LY | BA | Banghazi |
| LY | DR | Darnah |
| LY | MI | Misratah |
| LY | MQ | Murzuq |
| LY | SB | Sabha |
| LY | SR | Surt |
| LY | BU | Al Buţnān |
| LY | GT | Ghāt |
| LY | JG | Al Jabal al Gharbī |
| LY | JI | Al Jafārah |
| LY | MB | Al Marqab |
| LY | MJ | Al Marj |
| LY | NL | Nālūt |
| LY | TB | Ţarābulus |
| LY | WA | Al Wāḩāt |
| LY | WD | Wādī al Ḩayāt |
| LY | WS | Wādī ash Shāţi’ |
| LI | 01 | Balzers |
| LI | 02 | Eschen |
| LI | 03 | Gamprin |
| LI | 04 | Mauren |
| LI | 05 | Planken |
| LI | 06 | Ruggell |
| LI | 07 | Schaan |
| LI | 08 | Schellenberg |
| LI | 09 | Triesen |
| LI | 10 | Triesenberg |
| LI | 11 | Vaduz |
| LT | AL | Alytus |
| LT | 16 | Kaunas |
| LT | KL | Klaipeda |
| LT | 25 | Marijampole |
| LT | 33 | Panevezys |
| LT | 44 | Siauliai |
| LT | TA | Taurage |
| LT | TE | Telsiai |
| LT | UT | Utena |
| LT | 58 | Vilnius |
| LT | 01 | Akmenė |
| LT | 02 | Alytaus miestas |
| LT | 04 | Anykščiai |
| LT | 05 | Birštono |
| LT | 06 | Biržai |
| LT | 07 | Druskininkai |
| LT | 08 | Elektrėnai |
| LT | 09 | Ignalina |
| LT | 10 | Jonava |
| LT | 11 | Joniškis |
| LT | 12 | Jurbarkas |
| LT | 13 | Kaišiadorys |
| LT | 14 | Kalvarijos |
| LT | 15 | Kauno miestas |
| LT | 17 | Kazlų Rūdos |
| LT | 18 | Kėdainiai |
| LT | 19 | Kelmė |
| LT | 20 | Klaipėdos miestas |
| LT | 22 | Kretinga |
| LT | 23 | Kupiškis |
| LT | 24 | Lazdijai |
| LT | 26 | Mažeikiai |
| LT | 27 | Molėtai |
| LT | 28 | Neringa |
| LT | 29 | Pagėgiai |
| LT | 30 | Pakruojis |
| LT | 31 | Palangos miestas |
| LT | 32 | Panevėžio miestas |
| LT | 34 | Pasvalys |
| LT | 35 | Plungė |
| LT | 36 | Prienai |
| LT | 37 | Radviliškis |
| LT | 38 | Raseiniai |
| LT | 39 | Rietavo |
| LT | 40 | Rokiškis |
| LT | 41 | Šakiai |
| LT | 42 | Šalčininkai |
| LT | 43 | Šiaulių miestas |
| LT | 45 | Šilalė |
| LT | 46 | Šilutė |
| LT | 47 | Širvintos |
| LT | 48 | Skuodas |
| LT | 49 | Švenčionys |
| LT | 52 | Trakai |
| LT | 53 | Ukmergė |
| LT | 55 | Varėna |
| LT | 56 | Vilkaviškis |
| LT | 57 | Vilniaus miestas |
| LT | 59 | Visaginas |
| LT | 60 | Zarasai |
| LT | KU | Kauno apskritis |
| LT | MR | Marijampolės apskritis |
| LT | PN | Panevėžio apskritis |
| LT | SA | Šiaulių apskritis |
| LT | VL | Vilniaus apskritis |
| LU | CA | Capellen |
| LU | CL | Clervaux |
| LU | DI | Diekirch |
| LU | EC | Echternach |
| LU | ES | Esch-sur-Alzette |
| LU | GR | Grevenmacher |
| LU | LU | Luxembourg |
| LU | ME | Mersch |
| LU | RD | Redange |
| LU | RM | Remich |
| LU | VD | Vianden |
| LU | WI | Wiltz |
| MK | 101 | Veles |
| MK | 102 | Gradsko |
| MK | 103 | Demir Kapija |
| MK | 104 | Kavadarci |
| MK | 105 | Lozovo |
| MK | 106 | Negotino |
| MK | 107 | Rosoman |
| MK | 108 | Sveti Nikole |
| MK | 109 | Čaška |
| MK | 201 | Berovo |
| MK | 202 | Vinica |
| MK | 203 | Delčevo |
| MK | 204 | Zrnovci |
| MK | 205 | Karbinci |
| MK | 206 | Kočani |
| MK | 207 | Makedonska Kamenica |
| MK | 208 | Pehčevo |
| MK | 209 | Probištip |
| MK | 210 | Češinovo-Obleševo |
| MK | 211 | Štip |
| MK | 301 | Vevčani |
| MK | 303 | Debar |
| MK | 304 | Debrca |
| MK | 307 | Kičevo |
| MK | 308 | Makedonski Brod |
| MK | 310 | Ohrid |
| MK | 311 | Plasnica |
| MK | 312 | Struga |
| MK | 313 | Centar Župa |
| MK | 401 | Bogdanci |
| MK | 402 | Bosilovo |
| MK | 403 | Valandovo |
| MK | 404 | Vasilevo |
| MK | 405 | Gevgelija |
| MK | 406 | Dojran |
| MK | 407 | Konče |
| MK | 408 | Novo Selo |
| MK | 409 | Radoviš |
| MK | 410 | Strumica |
| MK | 501 | Bitola |
| MK | 502 | Demir Hisar |
| MK | 503 | Dolneni |
| MK | 504 | Krivogaštani |
| MK | 505 | Kruševo |
| MK | 506 | Mogila |
| MK | 507 | Novaci |
| MK | 508 | Prilep |
| MK | 509 | Resen |
| MK | 601 | Bogovinje |
| MK | 602 | Brvenica |
| MK | 603 | Vrapčište |
| MK | 604 | Gostivar |
| MK | 605 | Želino |
| MK | 606 | Jegunovce |
| MK | 607 | Mavrovo i Rostuše |
| MK | 608 | Tearce |
| MK | 609 | Tetovo |
| MK | 701 | Kratovo |
| MK | 702 | Kriva Palanka |
| MK | 703 | Kumanovo |
| MK | 704 | Lipkovo |
| MK | 705 | Rankovce |
| MK | 706 | Staro Nagoričane |
| MK | 801 | Aerodrom † |
| MK | 802 | Aračinovo |
| MK | 803 | Butel † |
| MK | 804 | Gazi Baba † |
| MK | 805 | Gjorče Petrov † |
| MK | 806 | Zelenikovo |
| MK | 807 | Ilinden |
| MK | 808 | Karpoš † |
| MK | 809 | Kisela Voda † |
| MK | 810 | Petrovec |
| MK | 811 | Saraj † |
| MK | 812 | Sopište |
| MK | 813 | Studeničani |
| MK | 814 | Centar † |
| MK | 815 | Čair † |
| MK | 816 | Čučer-Sandevo |
| MK | 817 | Šuto Orizari † |
| MG | T | Antananarivo |
| MG | D | Antsiranana |
| MG | F | Fianarantsoa |
| MG | M | Mahajanga |
| MG | A | Toamasina |
| MG | U | Toliara |
| MW | BA | Balaka |
| MW | BL | Blantyre |
| MW | CK | Chikwawa |
| MW | CR | Chiradzulu |
| MW | CT | Chitipa |
| MW | DE | Dedza |
| MW | DO | Dowa |
| MW | KR | Karonga |
| MW | KS | Kasungu |
| MW | LK | Likoma |
| MW | LI | Lilongwe |
| MW | MH | Machinga |
| MW | MG | Mangochi |
| MW | MC | Mchinji |
| MW | MU | Mulanje |
| MW | MW | Mwanza |
| MW | MZ | Mzimba |
| MW | NB | Nkhata Bay |
| MW | NK | Nkhotakota |
| MW | NS | Nsanje |
| MW | NU | Ntcheu |
| MW | NI | Ntchisi |
| MW | PH | Phalombe |
| MW | RU | Rumphi |
| MW | SA | Salima |
| MW | TH | Thyolo |
| MW | ZO | Zomba |
| MW | C | Chapakati |
| MW | N | Northern Region |
| MW | NE | Neno |
| MW | S | Southern Region |
| MY | 01 | Johor |
| MY | 02 | Kedah |
| MY | 03 | Kelantan |
| MY | 04 | Melaka |
| MY | 05 | Negeri Sembilan |
| MY | 06 | Pahang |
| MY | 08 | Perak |
| MY | 09 | Perlis |
| MY | 07 | Pulau Pinang |
| MY | 12 | Sabah |
| MY | 13 | Sarawak |
| MY | 10 | Selangor |
| MY | 11 | Terengganu |
| MY | 14 | Wilayah Persekutuan Kuala Lumpur |
| MY | 15 | Wilayah Persekutuan Labuan |
| MY | 16 | Wilayah Persekutuan Putrajaya |
| MV | 01 | Addu |
| MV | 03 | Faadhippolhu |
| MV | 08 | Kolhumadulu |
| MV | 26 | Male Atoll |
| MV | 12 | Mulaku Atoll |
| MV | 00 | South Ari Atoll |
| MV | 02 | North Ari Atoll |
| MV | 04 | Felidhu Atoll |
| MV | 05 | Hahdhunmathi |
| MV | 07 | Thiladhunmathee Uthuruburi |
| MV | 13 | North Maalhosmadulu |
| MV | 14 | North Nilandhe Atoll |
| MV | 17 | South Nilandhe Atoll |
| MV | 20 | South Maalhosmadulu |
| MV | 23 | Thiladhunmathee Dhekunuburi |
| MV | 24 | North Miladhunmadulu |
| MV | 25 | South Miladhunmadulu |
| MV | 27 | North Huvadhu Atoll |
| MV | 28 | South Huvadhu Atoll |
| MV | 29 | Fuvammulah |
| MV | MLE | Male |
| ML | 7 | Gao |
| ML | 1 | Kayes |
| ML | 8 | Kidal |
| ML | 2 | Koulikoro |
| ML | 5 | Mopti |
| ML | 4 | Segou |
| ML | 3 | Sikasso |
| ML | 6 | Tombouctou |
| ML | 10 | Taoudénit |
| ML | 9 | Ménaka |
| ML | BKO | Bamako |
| MT | 01 | Attard |
| MT | 02 | Balzan |
| MT | 03 | Birgu |
| MT | 04 | Birkirkara |
| MT | 05 | Birzebbuga |
| MT | 06 | Bormla |
| MT | 07 | Dingli |
| MT | 08 | Fgura |
| MT | 09 | Floriana |
| MT | 10 | Fontana |
| MT | 11 | Gudja |
| MT | 12 | Gzira |
| MT | 19 | Iklin |
| MT | 20 | Isla |
| MT | 21 | Kalkara |
| MT | 22 | Kercem |
| MT | 23 | Kirkop |
| MT | 24 | Lija |
| MT | 25 | Luqa |
| MT | 26 | Marsa |
| MT | 27 | Marsaskala |
| MT | 28 | Marsaxlokk |
| MT | 29 | Mdina |
| MT | 31 | Mgarr |
| MT | 32 | Mosta |
| MT | 33 | Mqabba |
| MT | 34 | Msida |
| MT | 35 | Mtarfa |
| MT | 36 | Munxar |
| MT | 37 | Nadur |
| MT | 38 | Naxxar |
| MT | 39 | Paola |
| MT | 40 | Pembroke |
| MT | 41 | Pieta |
| MT | 42 | Qala |
| MT | 43 | Qormi |
| MT | 44 | Qrendi |
| MT | 47 | Safi |
| MT | 48 | San Giljan |
| MT | 49 | San Gwann |
| MT | 50 | San Lawrenz |
| MT | 52 | Sannat |
| MT | 53 | Santa Lucija |
| MT | 54 | Santa Venera |
| MT | 55 | Siggiewi |
| MT | 56 | Sliema |
| MT | 57 | Swieqi |
| MT | 59 | Tarxien |
| MT | 60 | Valletta |
| MT | 62 | Xewkija |
| MT | 64 | Zabbar |
| MT | 67 | Zejtun |
| MT | 68 | Zurrieq |
| MT | 13 | Għajnsielem |
| MT | 14 | Għarb |
| MT | 15 | Għargħur |
| MT | 16 | Għasri |
| MT | 17 | Għaxaq |
| MT | 18 | Ħamrun |
| MT | 30 | Mellieħa |
| MT | 45 | Rabat Għawdex |
| MT | 46 | Rabat Malta |
| MT | 51 | San Pawl il-Baħar |
| MT | 58 | Ta’ Xbiex |
| MT | 61 | Xagħra |
| MT | 63 | Xgħajra |
| MT | 65 | Żebbuġ Għawdex |
| MT | 66 | Żebbuġ Malta |
| MH | ALL | Ailinglaplap |
| MH | ALK | Ailuk |
| MH | ARN | Arno |
| MH | AUR | Aur |
| MH | EBO | Ebon |
| MH | JAB | Jabat |
| MH | JAL | Jaluit |
| MH | KIL | Kili |
| MH | KWA | Kwajalein |
| MH | LAE | Lae |
| MH | LIB | Lib |
| MH | LIK | Likiep |
| MH | MAJ | Majuro |
| MH | MAL | Maloelap |
| MH | MEJ | Mejit |
| MH | MIL | Mili |
| MH | NMK | Namorik |
| MH | NMU | Namu |
| MH | RON | Rongelap |
| MH | UJA | Ujae |
| MH | WTH | Wotho |
| MH | WTJ | Wotje |
| MH | ENI | Enewetak & Ujelang |
| MH | L | Ralik chain |
| MH | T | Ratak chain |
| MH | UTI | Utrōk |
| MR | 07 | Adrar |
| MR | 03 | Assaba |
| MR | 05 | Brakna |
| MR | 08 | Dakhlet Nouadhibou |
| MR | 04 | Gorgol |
| MR | 10 | Guidimaka |
| MR | 01 | Hodh Ech Chargui |
| MR | 02 | Hodh El Gharbi |
| MR | 12 | Inchiri |
| MR | 09 | Tagant |
| MR | 11 | Tiris Zemmour |
| MR | 06 | Trarza |
| MR | 13 | Nuwākshūţ al Gharbīyah |
| MR | 14 | Nuwākshūţ ash Shamālīyah |
| MR | 15 | Nuwākshūţ al Janūbīyah |
| MU | AG | Agalega Islands |
| MU | BL | Black River |
| MU | CC | Cargados Carajos Shoals (Saint Brandon Islands) |
| MU | FL | Flacq |
| MU | GP | Grand Port |
| MU | MO | Moka |
| MU | PA | Pamplemousses |
| MU | PW | Plaines Wilhems |
| MU | PL | Port Louis |
| MU | RR | Riviere du Rempart |
| MU | RO | Rodrigues |
| MU | SA | Savanne |
| MX | AGU | Aguascalientes |
| MX | BCS | Baja California Sur |
| MX | CAM | Campeche |
| MX | CHP | Chiapas |
| MX | CHH | Chihuahua |
| MX | COA | Coahuila de Zaragoza |
| MX | COL | Colima |
| MX | DUR | Durango |
| MX | GUA | Guanajuato |
| MX | GRO | Guerrero |
| MX | HID | Hidalgo |
| MX | JAL | Jalisco |
| MX | MEX | Mexico |
| MX | MIC | Michoacan de Ocampo |
| MX | MOR | Morelos |
| MX | NAY | Nayarit |
| MX | NLE | Nuevo Leon |
| MX | OAX | Oaxaca |
| MX | PUE | Puebla |
| MX | ROO | Quintana Roo |
| MX | SLP | San Luis Potosi |
| MX | SIN | Sinaloa |
| MX | SON | Sonora |
| MX | TAB | Tabasco |
| MX | TAM | Tamaulipas |
| MX | TLA | Tlaxcala |
| MX | YUC | Yucatan |
| MX | ZAC | Zacatecas |
| MX | BCN | Baja California |
| MX | CMX | Ciudad de México |
| MX | QUE | Querétaro |
| MX | VER | Veracruz de Ignacio de la Llave |
| FM | TRK | Chuuk |
| FM | KSA | Kosrae |
| FM | PNI | Pohnpei |
| FM | YAP | Yap |
| MD | BA | Balti |
| MD | CA | Cahul |
| MD | CU | Chisinau |
| MD | ED | Edinet |
| MD | GA | Gagauzia |
| MD | OR | Orhei |
| MD | SO | Soroca |
| MD | SN | Stînga Nistrului |
| MD | UN | Ungheni |
| MD | AN | Anenii Noi |
| MD | BD | Bender [Tighina] |
| MD | BR | Briceni |
| MD | BS | Basarabeasca |
| MD | CL | Călărași |
| MD | CM | Cimișlia |
| MD | CR | Criuleni |
| MD | CS | Căușeni |
| MD | CT | Cantemir |
| MD | DO | Dondușeni |
| MD | DR | Drochia |
| MD | DU | Dubăsari |
| MD | FA | Fălești |
| MD | FL | Florești |
| MD | GL | Glodeni |
| MD | HI | Hîncești |
| MD | IA | Ialoveni |
| MD | LE | Leova |
| MD | NI | Nisporeni |
| MD | OC | Ocnița |
| MD | RE | Rezina |
| MD | RI | Rîșcani |
| MD | SD | Șoldănești |
| MD | SI | Sîngerei |
| MD | ST | Strășeni |
| MD | SV | Ștefan Vodă |
| MD | TA | Taraclia |
| MD | TE | Telenești |
| MC | FO | Fontvieille |
| MC | CO | La Condamine |
| MC | MO | Monaco-Ville |
| MC | MC | Monte-Carlo |
| MC | CL | La Colle |
| MC | GA | La Gare |
| MC | JE | Jardin Exotique |
| MC | LA | Larvotto |
| MC | MA | Malbousquet |
| MC | MG | Moneghetti |
| MC | MU | Moulins |
| MC | PH | Port-Hercule |
| MC | SD | Sainte-Dévote |
| MC | SO | La Source |
| MC | SP | Spélugues |
| MC | SR | Saint-Roman |
| MC | VR | Vallon de la Rousse |
| MN | 073 | Arhangay |
| MN | 071 | Bayan-Olgiy |
| MN | 069 | Bayanhongor |
| MN | 067 | Bulgan |
| MN | 037 | Darhan uul |
| MN | 061 | Dornod |
| MN | 057 | Dzavhan |
| MN | 065 | Govi-Altay |
| MN | 064 | Govi-Sumber |
| MN | 039 | Hentiy |
| MN | 043 | Hovd |
| MN | 041 | Hovsgol |
| MN | 053 | Omnogovi |
| MN | 035 | Orhon |
| MN | 055 | Ovorhangay |
| MN | 049 | Selenge |
| MN | 051 | Suhbaatar |
| MN | 047 | Tov |
| MN | 1 | Ulanbaatar |
| MN | 046 | Uvs |
| MN | 059 | Dundgovĭ |
| MN | 063 | Dornogovĭ |
| ME | 01 | Andrijevica |
| ME | 02 | Bar |
| ME | 03 | Berane |
| ME | 04 | Bijelo Polje |
| ME | 05 | Budva |
| ME | 06 | Cetinje |
| ME | 07 | Danilovgrad |
| ME | 08 | Herceg-Novi |
| ME | 09 | Kolašin |
| ME | 10 | Kotor |
| ME | 11 | Mojkovac |
| ME | 12 | Nikšić |
| ME | 13 | Plav |
| ME | 14 | Pljevlja |
| ME | 15 | Plužine |
| ME | 16 | Podgorica |
| ME | 17 | Rožaje |
| ME | 18 | Šavnik |
| ME | 19 | Tivat |
| ME | 20 | Ulcinj |
| ME | 21 | Žabljak |
| ME | 22 | Gusinje |
| ME | 23 | Petnjica |
| ME | 24 | Tuzi |
| MA | AGD | Agadir |
| MA | HOC | Al Hoceima |
| MA | AZI | Azilal |
| MA | BEM | Beni Mellal |
| MA | BOM | Boulemane |
| MA | CAS | Casablanca |
| MA | JDI | El Jadida |
| MA | KES | El Kelaa des Sraghna |
| MA | ESM | Es Smara |
| MA | ESI | Essaouira |
| MA | FES | Fes |
| MA | FIG | Figuig |
| MA | GUE | Guelmim |
| MA | IFR | Ifrane |
| MA | KEN | Kenitra |
| MA | KHE | Khemisset |
| MA | KHN | Khenifra |
| MA | KHO | Khouribga |
| MA | LAR | Larache |
| MA | MAR | Marrakech |
| MA | MEK | Meknes |
| MA | NAD | Nador |
| MA | OUA | Ouarzazate |
| MA | OUJ | Oujda |
| MA | SAF | Safi |
| MA | SET | Settat |
| MA | SIK | Sidi Kacem |
| MA | TAO | Taounate |
| MA | TAR | Taroudannt |
| MA | TAT | Tata |
| MA | TAZ | Taza |
| MA | TET | Tetouan |
| MA | TIZ | Tiznit |
| MA | 01 | Tanger-Tétouan-Al Hoceïma |
| MA | 02 | L’Oriental |
| MA | 03 | Fès-Meknès |
| MA | 04 | Rabat-Salé-Kénitra |
| MA | 05 | Béni Mellal-Khénifra |
| MA | 06 | Casablanca-Settat |
| MA | 07 | Marrakech-Safi |
| MA | 08 | Drâa-Tafilalet |
| MA | 09 | Souss-Massa |
| MA | 10 | Guelmim-Oued Noun (EH-partial) |
| MA | 11 | Laâyoune-Sakia El Hamra (EH-partial) |
| MA | 12 | Dakhla-Oued Ed-Dahab (EH) |
| MA | AOU | Aousserd (EH) |
| MA | ASZ | Assa-Zag (EH-partial) |
| MA | BER | Berkane |
| MA | BES | Benslimane |
| MA | BOD | Boujdour (EH) |
| MA | BRR | Berrechid |
| MA | CHE | Chefchaouen |
| MA | CHI | Chichaoua |
| MA | CHT | Chtouka-Ait Baha |
| MA | DRI | Driouch |
| MA | ERR | Errachidia |
| MA | FAH | Fahs-Anjra |
| MA | FQH | Fquih Ben Salah |
| MA | GUF | Guercif |
| MA | HAJ | El Hajeb |
| MA | HAO | Al Haouz |
| MA | INE | Inezgane-Ait Melloul |
| MA | JRA | Jerada |
| MA | LAA | Laâyoune (EH) |
| MA | MDF | M’diq-Fnideq |
| MA | MED | Médiouna |
| MA | MID | Midelt |
| MA | MOH | Mohammadia |
| MA | MOU | Moulay Yacoub |
| MA | NOU | Nouaceur |
| MA | OUD | Oued Ed-Dahab (EH) |
| MA | OUZ | Ouezzane |
| MA | RAB | Rabat |
| MA | REH | Rehamna |
| MA | SAL | Salé |
| MA | SEF | Sefrou |
| MA | SIB | Sidi Bennour |
| MA | SIF | Sidi Ifni |
| MA | SIL | Sidi Slimane |
| MA | SKH | Skhirate-Témara |
| MA | TAF | Tarfaya (EH-partial) |
| MA | TAI | Taourirt |
| MA | TIN | Tinghir |
| MA | TNG | Tanger-Assilah |
| MA | TNT | Tan-Tan (EH-partial) |
| MA | YUS | Youssoufia |
| MA | ZAG | Zagora |
| MZ | P | Cabo Delgado |
| MZ | G | Gaza |
| MZ | I | Inhambane |
| MZ | B | Manica |
| MZ | MPM | Maputo |
| MZ | N | Nampula |
| MZ | A | Niassa |
| MZ | S | Sofala |
| MZ | T | Tete |
| MZ | Q | Zambezia |
| MM | 07 | Ayeyarwady |
| MM | 02 | Bago |
| MM | 03 | Magway |
| MM | 04 | Mandalay |
| MM | 01 | Sagaing |
| MM | 05 | Tanintharyi |
| MM | 06 | Yangon |
| MM | 11 | Kachin |
| MM | 12 | Kayah |
| MM | 13 | Kayin |
| MM | 14 | Chin |
| MM | 15 | Mon |
| MM | 16 | Rakhine |
| MM | 17 | Shan |
| MM | 18 | Nay Pyi Taw |
| NA | CA | Caprivi |
| NA | ER | Erongo |
| NA | HA | Hardap |
| NA | KH | Khomas |
| NA | KU | Kunene |
| NA | OW | Ohangwena |
| NA | OH | Omaheke |
| NA | OS | Omusati |
| NA | ON | Oshana |
| NA | OT | Oshikoto |
| NA | OD | Otjozondjupa |
| NA | KA | //Karas |
| NA | KE | Kavango East |
| NA | KW | Kavango West |
| NR | 01 | Aiwo |
| NR | 02 | Anabar |
| NR | 03 | Anetan |
| NR | 04 | Anibare |
| NR | 06 | Boe |
| NR | 07 | Buada |
| NR | 08 | Denigomodu |
| NR | 09 | Ewa |
| NR | 10 | Ijuw |
| NR | 11 | Meneng |
| NR | 12 | Nibok |
| NR | 13 | Uaboe |
| NR | 14 | Yaren |
| NR | 05 | Baitsi |
| NP | BA | Bagmati |
| NP | BH | Bheri |
| NP | DH | Dhawalagiri |
| NP | GA | Gandaki |
| NP | JA | Janakpur |
| NP | KA | Karnali |
| NP | KO | Kosi |
| NP | LU | Lumbini |
| NP | MA | Mahakali |
| NP | ME | Mechi |
| NP | NA | Narayani |
| NP | RA | Rapti |
| NP | SA | Sagarmatha |
| NP | SE | Seti |
| NP | 1 | Madhyamanchal |
| NP | 2 | Mid Western |
| NP | 3 | Western |
| NP | 4 | Purwanchal |
| NP | 5 | Sudur Pashchimanchal |
| NP | P1 | Province 1 |
| NP | P2 | Province 2 |
| NP | P5 | Province 5 |
| NP | P7 | Sudūr Pashchim |
| NL | DR | Drenthe |
| NL | FL | Flevoland |
| NL | FR | Friesland |
| NL | GE | Gelderland |
| NL | GR | Groningen |
| NL | LI | Limburg |
| NL | NB | Noord Brabant |
| NL | NH | Noord Holland |
| NL | OV | Overijssel |
| NL | UT | Utrecht |
| NL | ZE | Zeeland |
| NL | ZH | Zuid Holland |
| NL | AW | Aruba (see also separate country code entry under AW) |
| NL | BQ1 | Bonaire (see also separate country code entry under BQ) |
| NL | BQ2 | Saba (see also separate country code entry under BQ) |
| NL | BQ3 | Sint Eustatius (see also separate country code entry under BQ) |
| NL | CW | Curaçao (see also separate country code entry under CW) |
| NL | SX | Sint Maarten (see also separate country code entry under SX) |
| NZ | AUK | Auckland |
| NZ | BOP | Bay of Plenty |
| NZ | CAN | Canterbury |
| NZ | GIS | Gisborne |
| NZ | HKB | Hawke’s Bay |
| NZ | MWT | Manawatu-Wanganui |
| NZ | MBH | Marlborough |
| NZ | NSN | Nelson |
| NZ | NTL | Northland |
| NZ | OTA | Otago |
| NZ | STL | Southland |
| NZ | TKI | Taranaki |
| NZ | WKO | Waikato |
| NZ | WGN | Wellington |
| NZ | WTC | West Coast |
| NZ | CIT | Wharekauri |
| NZ | TAS | Tasman |
| NI | AN | Atlantico Norte |
| NI | AS | Atlantico Sur |
| NI | BO | Boaco |
| NI | CA | Carazo |
| NI | CI | Chinandega |
| NI | CO | Chontales |
| NI | ES | Esteli |
| NI | GR | Granada |
| NI | JI | Jinotega |
| NI | LE | Leon |
| NI | MD | Madriz |
| NI | MN | Managua |
| NI | MS | Masaya |
| NI | MT | Matagalpa |
| NI | NS | Nuevo Segovia |
| NI | SJ | Rio San Juan |
| NI | RI | Rivas |
| NE | 1 | Agadez |
| NE | 2 | Diffa |
| NE | 3 | Dosso |
| NE | 4 | Maradi |
| NE | 8 | Niamey |
| NE | 5 | Tahoua |
| NE | 6 | Tillaberi |
| NE | 7 | Zinder |
| NG | AB | Abia |
| NG | FC | Abuja Federal Capital Territory |
| NG | AD | Adamawa |
| NG | AK | Akwa Ibom |
| NG | AN | Anambra |
| NG | BA | Bauchi |
| NG | BY | Bayelsa |
| NG | BE | Benue |
| NG | BO | Borno |
| NG | CR | Cross River |
| NG | DE | Delta |
| NG | EB | Ebonyi |
| NG | ED | Edo |
| NG | EK | Ekiti |
| NG | EN | Enugu |
| NG | GO | Gombe |
| NG | IM | Imo |
| NG | JI | Jigawa |
| NG | KD | Kaduna |
| NG | KN | Kano |
| NG | KT | Katsina |
| NG | KE | Kebbi |
| NG | KO | Kogi |
| NG | KW | Kwara |
| NG | LA | Lagos |
| NG | NA | Nassarawa |
| NG | NI | Niger |
| NG | OG | Ogun |
| NG | ON | Ondo |
| NG | OS | Osun |
| NG | OY | Oyo |
| NG | PL | Plateau |
| NG | RI | Rivers |
| NG | SO | Sokoto |
| NG | TA | Taraba |
| NG | YO | Yobe |
| NG | ZA | Zamfara |
| NO | 18 | Nordland |
| NO | 03 | Oslo |
| NO | 11 | Rogaland |
| NO | 15 | Møre og Romsdal |
| NO | 21 | Svalbard (Arctic Region) (see also separate country code entry under SJ) |
| NO | 22 | Jan Mayen (Arctic Region) (see also separate country code entry under SJ) |
| NO | 30 | Viken |
| NO | 34 | Innlandet |
| NO | 38 | Vestfold og Telemark |
| NO | 42 | Agder |
| NO | 46 | Vestland |
| NO | 50 | Trøndelag |
| NO | 54 | Tromssan ja Finmarkun |
| OM | DA | Ad Dakhiliyah |
| OM | WU | Al Wusta |
| OM | ZA | Az Zahirah |
| OM | MA | Masqat |
| OM | MU | Musandam |
| OM | ZU | Zufar |
| OM | BJ | Janūb al Bāţinah |
| OM | BS | Shamāl al Bāţinah |
| OM | BU | Al Buraymī |
| OM | SJ | Janūb ash Sharqīyah |
| OM | SS | Shamāl ash Sharqīyah |
| PK | BA | Balochistan |
| PK | PB | Punjab |
| PK | SD | Sindh |
| PK | GB | Gilgit-Baltistan |
| PK | IS | Islamabad |
| PK | JK | Āzād Jammūñ o Kashmīr |
| PK | KP | Khyber Pakhtunkhwa |
| PW | 002 | Aimeliik |
| PW | 004 | Airai |
| PW | 010 | Angaur |
| PW | 050 | Hatohobei |
| PW | 100 | Kayangel |
| PW | 150 | Koror |
| PW | 212 | Melekeok |
| PW | 214 | Ngaraard |
| PW | 218 | Ngarchelong |
| PW | 222 | Ngardmau |
| PW | 224 | Ngatpang |
| PW | 226 | Ngchesar |
| PW | 227 | Ngeremlengui |
| PW | 228 | Ngiwal |
| PW | 350 | Peleliu |
| PW | 370 | Sonsorol |
| PS | BTH | Bethlehem |
| PS | DEB | Deir El Balah |
| PS | GZA | Ghazzah |
| PS | HBN | Hebron |
| PS | JEM | Jerusalem |
| PS | JEN | Jenin |
| PS | JRH | Jericho and Al Aghwar |
| PS | KYS | Khān Yūnis |
| PS | NBS | Nāblus |
| PS | NGZ | Shamāl Ghazzah |
| PS | QQA | Qalqīlyah |
| PS | RBH | Ramallah |
| PS | RFH | Rafaḩ |
| PS | SLT | Salfīt |
| PS | TBS | Ţūbās |
| PS | TKM | Ţūlkarm |
| PA | 1 | Bocas del Toro |
| PA | 4 | Chiriqui |
| PA | 2 | Cocle |
| PA | 3 | Colon |
| PA | 5 | Darien |
| PA | 6 | Herrera |
| PA | 7 | Los Santos |
| PA | 8 | Panama |
| PA | 9 | Veraguas |
| PA | 10 | Panamá Oeste |
| PA | EM | Emberá |
| PA | KY | Guna Yala |
| PA | NB | Ngöbe-Buglé |
| PG | NSB | Bougainville |
| PG | CPM | Central |
| PG | CPK | Chimbu |
| PG | EBR | East New Britain |
| PG | ESW | East Sepik |
| PG | EHG | Eastern Highlands |
| PG | EPW | Enga |
| PG | GPK | Gulf |
| PG | MPM | Madang |
| PG | MRL | Manus |
| PG | MBA | Milne Bay |
| PG | MPL | Morobe |
| PG | NIK | New Ireland |
| PG | NPP | Northern |
| PG | SHM | Southern Highlands |
| PG | WBK | West New Britain |
| PG | WPD | Western |
| PG | WHM | Western Highlands |
| PG | HLA | Hela |
| PG | JWK | Jiwaka |
| PG | NCD | National Capital District (Port Moresby) |
| PG | SAN | West Sepik |
| PY | 16 | Alto Paraguay |
| PY | 10 | Alto Parana |
| PY | 13 | Amambay |
| PY | ASU | Asuncion |
| PY | 19 | Boqueron |
| PY | 5 | Caaguazu |
| PY | 6 | Caazapa |
| PY | 14 | Canindeyu |
| PY | 11 | Central |
| PY | 1 | Concepcion |
| PY | 3 | Cordillera |
| PY | 4 | Guaira |
| PY | 7 | Itapua |
| PY | 8 | Misiones |
| PY | 12 | Neembucu |
| PY | 9 | Paraguari |
| PY | 15 | Presidente Hayes |
| PY | 2 | San Pedro |
| PE | AMA | Amazonas |
| PE | ANC | Ancash |
| PE | APU | Apurimac |
| PE | ARE | Arequipa |
| PE | AYA | Ayacucho |
| PE | CAJ | Cajamarca |
| PE | CUS | Cusco |
| PE | HUV | Huancavelica |
| PE | HUC | Huanuco |
| PE | ICA | Ica |
| PE | JUN | Junin |
| PE | LAL | La Libertad |
| PE | LAM | Lambayeque |
| PE | LIM | Lima |
| PE | LOR | Loreto |
| PE | MDD | Madre de Dios |
| PE | MOQ | Moquegua |
| PE | PAS | Pasco |
| PE | PIU | Piura |
| PE | PUN | Puno |
| PE | SAM | San Martin |
| PE | TAC | Tacna |
| PE | TUM | Tumbes |
| PE | UCA | Ucayali |
| PE | CAL | Qallaw |
| PE | LMA | Municipalidad Metropolitana de Lima |
| PH | ABR | Abra |
| PH | AGN | Agusan del Norte |
| PH | AGS | Agusan del Sur |
| PH | AKL | Aklan |
| PH | ALB | Albay |
| PH | ANT | Antique |
| PH | APA | Apayao |
| PH | AUR | Aurora |
| PH | BAS | Basilan |
| PH | BAN | Bataan |
| PH | BTN | Batanes |
| PH | BTG | Batangas |
| PH | BEN | Benguet |
| PH | BIL | Biliran |
| PH | BOH | Bohol |
| PH | BUK | Bukidnon |
| PH | BUL | Bulacan |
| PH | CAG | Cagayan |
| PH | CAN | Camarines Norte |
| PH | CAS | Camarines Sur |
| PH | CAM | Camiguin |
| PH | CAP | Capiz |
| PH | CAT | Catanduanes |
| PH | CAV | Cavite |
| PH | CEB | Cebu |
| PH | DAO | Davao Oriental |
| PH | DAV | Davao del Norte |
| PH | DAS | Davao del Sur |
| PH | EAS | Eastern Samar |
| PH | GUI | Guimaras |
| PH | IFU | Ifugao |
| PH | ILN | Ilocos Norte |
| PH | ILS | Ilocos Sur |
| PH | ILI | Iloilo |
| PH | ISA | Isabela |
| PH | KAL | Kalinga |
| PH | LUN | La Union |
| PH | LAG | Laguna |
| PH | LAN | Lanao del Norte |
| PH | LAS | Lanao del Sur |
| PH | LEY | Leyte |
| PH | MAG | Maguindanao |
| PH | MAD | Marinduque |
| PH | MAS | Masbate |
| PH | MDC | Mindoro Occidental |
| PH | MDR | Mindoro Oriental |
| PH | MSC | Misamis Occidental |
| PH | MSR | Misamis Oriental |
| PH | NEC | Negros Occidental |
| PH | NER | Negros Oriental |
| PH | NSA | Northern Samar |
| PH | NUE | Nueva Ecija |
| PH | NUV | Nueva Vizcaya |
| PH | PLW | Palawan |
| PH | PAM | Pampanga |
| PH | PAN | Pangasinan |
| PH | QUE | Quezon |
| PH | QUI | Quirino |
| PH | RIZ | Rizal |
| PH | ROM | Romblon |
| PH | WSA | Samar |
| PH | SAR | Sarangani |
| PH | SIG | Siquijor |
| PH | SOR | Sorsogon |
| PH | SCO | South Cotabato |
| PH | SLE | Southern Leyte |
| PH | SUK | Sultan Kudarat |
| PH | SLU | Sulu |
| PH | SUN | Surigao del Norte |
| PH | SUR | Surigao del Sur |
| PH | TAR | Tarlac |
| PH | TAW | Tawi-Tawi |
| PH | ZMB | Zambales |
| PH | ZSI | Zamboanga Sibugay |
| PH | ZAN | Zamboanga del Norte |
| PH | ZAS | Zamboanga del Sur |
| PH | 00 | Pambansang Punong Rehiyon |
| PH | 01 | Rehiyon ng Iloko |
| PH | 02 | Rehiyon ng Lambak ng Kagayan |
| PH | 03 | Rehiyon ng Gitnang Luson |
| PH | 05 | Rehiyon ng Bikol |
| PH | 06 | Western Visayas (Region VI) |
| PH | 07 | Rehiyon ng Gitnang Bisaya |
| PH | 08 | Rehiyon ng Silangang Bisaya |
| PH | 09 | Zamboanga Peninsula (Region IX) |
| PH | 10 | Rehiyon ng Hilagang Mindanaw |
| PH | 11 | Rehiyon ng Dabaw |
| PH | 12 | Soccsksargen (Region XII) |
| PH | 13 | Rehiyon ng Karaga |
| PH | 14 | Nagsasariling Rehiyon ng Muslim sa Mindanaw |
| PH | 15 | Rehiyon ng Administratibo ng Kordilyera |
| PH | 40 | Rehiyon ng Calabarzon |
| PH | 41 | Rehiyon ng Mimaropa |
| PH | COM | Davao de Oro |
| PH | DIN | Pulo ng Dinagat |
| PH | DVO | Kanlurang Dabaw |
| PH | MOU | Mountain Province |
| PH | NCO | Kotabato |
| PL | 02 | Dolnoslaskie |
| PL | 04 | Kujawsko-Pomorskie |
| PL | 06 | Lubelskie |
| PL | 08 | Lubuskie |
| PL | 14 | Mazowieckie |
| PL | 16 | Opolskie |
| PL | 18 | Podkarpackie |
| PL | 20 | Podlaskie |
| PL | 22 | Pomorskie |
| PL | 24 | Slaskie |
| PL | 26 | Swietokrzyskie |
| PL | 28 | Warminsko-Mazurskie |
| PL | 30 | Wielkopolskie |
| PL | 32 | Zachodniopomorskie |
| PL | 10 | Łódzkie |
| PL | 12 | Małopolskie |
| PT | 07 | Évora |
| PT | 01 | Aveiro |
| PT | 02 | Beja |
| PT | 03 | Braga |
| PT | 04 | Bragança |
| PT | 05 | Castelo Branco |
| PT | 06 | Coimbra |
| PT | 08 | Faro |
| PT | 09 | Guarda |
| PT | 10 | Leiria |
| PT | 11 | Lisboa |
| PT | 12 | Portalegre |
| PT | 13 | Porto |
| PT | 14 | Santarém |
| PT | 15 | Setúbal |
| PT | 16 | Viana do Castelo |
| PT | 17 | Vila Real |
| PT | 18 | Viseu |
| PT | 20 | Região Autónoma dos Açores |
| PT | 30 | Região Autónoma da Madeira |
| QA | DA | Ad Dawhah |
| QA | WA | Al Wakrah |
| QA | RA | Ar Rayyan |
| QA | MS | Madinat ash Shamal |
| QA | US | Umm Salal |
| QA | KH | Al Khawr wa adh Dhakhīrah |
| QA | SH | Ash Shīḩānīyah |
| QA | ZA | Az̧ Z̧a‘āyin |
| RO | AB | Alba |
| RO | AR | Arad |
| RO | AG | Arges |
| RO | BC | Bacau |
| RO | BH | Bihor |
| RO | BN | Bistrita-Nasaud |
| RO | BT | Botosani |
| RO | BR | Braila |
| RO | BV | Brasov |
| RO | B | Bucuresti |
| RO | BZ | Buzau |
| RO | CL | Calarasi |
| RO | CS | Caras-Severin |
| RO | CJ | Cluj |
| RO | CT | Constanta |
| RO | CV | Covasna |
| RO | DB | Dimbovita |
| RO | DJ | Dolj |
| RO | GL | Galati |
| RO | GR | Giurgiu |
| RO | GJ | Gorj |
| RO | HR | Harghita |
| RO | HD | Hunedoara |
| RO | IL | Ialomita |
| RO | IS | Iasi |
| RO | IF | Ilfov |
| RO | MM | Maramures |
| RO | MH | Mehedinti |
| RO | MS | Mures |
| RO | NT | Neamt |
| RO | OT | Olt |
| RO | PH | Prahova |
| RO | SJ | Salaj |
| RO | SM | Satu-Mare |
| RO | SB | Sibiu |
| RO | SV | Suceava |
| RO | TR | Teleorman |
| RO | TM | Timis |
| RO | TL | Tulcea |
| RO | VL | Valcea |
| RO | VS | Vaslui |
| RO | VN | Vrancea |
| RU | BA | Barnaul |
| RU | KL | Kaluga |
| RU | KO | Kostroma |
| RU | KR | Krasnodar |
| RU | KK | Kursk |
| RU | MO | Moscow |
| RU | SA | Samara |
| RU | TA | Tambov |
| RU | TY | Tyumen |
| RU | AD | “Adygeya, Respublika” |
| RU | AL | “Altay, Respublika” |
| RU | ALT | Altayskiy kray |
| RU | AMU | Amurskaya oblast’ |
| RU | ARK | Arkhangel’skaya oblast’ |
| RU | AST | Astrakhanskaya oblast’ |
| RU | BEL | Belgorodskaya oblast’ |
| RU | BRY | Bryanskaya oblast’ |
| RU | BU | “Buryatiya, Respublika” |
| RU | CE | Chechenskaya Respublika |
| RU | CHE | Chelyabinskaya oblast’ |
| RU | CHU | Čukotskij avtonomnyj okrug |
| RU | CU | Čuvašskaja Respublika |
| RU | DA | “Dagestan, Respublika” |
| RU | IN | “Ingushetiya, Respublika” |
| RU | IRK | Irkutskaya oblast’ |
| RU | IVA | Ivanovskaya oblast’ |
| RU | KAM | Kamchatskiy kray |
| RU | KB | Kabardino-Balkarskaya Respublika |
| RU | KC | Karachayevo-Cherkesskaya Respublika |
| RU | KDA | Krasnodarskiy kray |
| RU | KEM | Kemerovskaya oblast’ |
| RU | KGD | Kaliningradskaya oblast’ |
| RU | KGN | Kurganskaya oblast’ |
| RU | KHA | Khabarovskiy kray |
| RU | KHM | Khanty-Mansiyskiy avtonomnyy okrug |
| RU | KIR | Kirovskaya oblast’ |
| RU | KLU | Kalužskaja oblast’ |
| RU | KOS | Kostromskaya oblast’ |
| RU | KRS | Kurskaya oblast’ |
| RU | KYA | Krasnoyarskiy kray |
| RU | LEN | Leningradskaya oblast’ |
| RU | LIP | Lipetskaya oblast’ |
| RU | MAG | Magadanskaya oblast’ |
| RU | ME | “Mariy El, Respublika” |
| RU | MOS | Moskovskaya oblast’ |
| RU | MOW | Moskva |
| RU | MUR | Murmanskaya oblast’ |
| RU | NEN | Nenetskiy avtonomnyy okrug |
| RU | NGR | Novgorodskaya oblast’ |
| RU | NIZ | Nizhegorodskaya oblast’ |
| RU | NVS | Novosibirskaya oblast’ |
| RU | OMS | Omskaya oblast’ |
| RU | ORE | Orenburgskaya oblast’ |
| RU | ORL | Orlovskaya oblast’ |
| RU | PER | Permskiy kray |
| RU | PNZ | Penzenskaya oblast’ |
| RU | PRI | Primorskiy kray |
| RU | PSK | Pskovskaya oblast’ |
| RU | ROS | Rostovskaya oblast’ |
| RU | RYA | Ryazanskaya oblast’ |
| RU | SAK | Sakhalinskaya oblast’ |
| RU | SAM | Samarskaya oblast’ |
| RU | SAR | Saratovskaya oblast’ |
| RU | SE | “Severnaya Osetiya, Respublika” |
| RU | SMO | Smolenskaya oblast’ |
| RU | SPE | Sankt-Peterburg |
| RU | STA | Stavropol’skiy kray |
| RU | SVE | Sverdlovskaya oblast’ |
| RU | TAM | Tambovskaya oblast’ |
| RU | TOM | Tomskaya oblast’ |
| RU | TUL | Tul’skaya oblast’ |
| RU | TVE | Tverskaya oblast’ |
| RU | TYU | Tyumenskaya oblast’ |
| RU | UD | Udmurtskaya Respublika |
| RU | ULY | Ul’yanovskaya oblast’ |
| RU | VGG | Volgogradskaya oblast’ |
| RU | VLA | Vladimirskaya oblast’ |
| RU | VLG | Vologodskaya oblast’ |
| RU | VOR | Voronežskaja oblast’ |
| RU | YAN | Yamalo-Nenetskiy avtonomnyy okrug |
| RU | YAR | Yaroslavskaya oblast’ |
| RU | YEV | Yevreyskaya avtonomnaya oblast’ |
| RU | ZAB | Zabaykal’skiy kray |
| RW | 01 | Ville de Kigali |
| RW | 02 | Iburasirazuba |
| RW | 03 | Northern |
| RW | 04 | Western |
| RW | 05 | Sud |
| SH | AC | Ascension |
| SH | HL | Saint Helena |
| SH | TA | Tristan da Cunha |
| KN | 01 | Christ Church Nichola Town |
| KN | 02 | Saint Anne Sandy Point |
| KN | 03 | Saint George Basseterre |
| KN | 04 | Saint George Gingerland |
| KN | 05 | Saint James Windward |
| KN | 07 | Saint John Figtree |
| KN | 08 | Saint Mary Cayon |
| KN | 10 | Saint Paul Charlestown |
| KN | 11 | Saint Peter Basseterre |
| KN | 12 | Saint Thomas Lowland |
| KN | 13 | Saint Thomas Middle Island |
| KN | 15 | Trinity Palmetto Point |
| KN | 06 | Saint John Capisterre |
| KN | 09 | Saint Paul Capisterre |
| KN | K | Saint Kitts |
| KN | N | Nevis |
| LC | 02 | Castries |
| LC | 03 | Choiseul |
| LC | 05 | Dennery |
| LC | 07 | Laborie |
| LC | 08 | Micoud |
| LC | 10 | Soufriere |
| LC | 01 | Anse la Raye |
| LC | 06 | Gros Islet |
| LC | 11 | Vieux Fort |
| LC | 12 | Canaries |
| VC | 01 | Charlotte |
| VC | 06 | Grenadines |
| VC | 02 | Saint Andrew |
| VC | 03 | Saint David |
| VC | 04 | Saint George |
| VC | 05 | Saint Patrick |
| WS | AA | A’ana |
| WS | AL | Aiga-i-le-Tai |
| WS | AT | Atua |
| WS | FA | Fa’asaleleaga |
| WS | GE | Gaga’emauga |
| WS | GI | Gagaifomauga |
| WS | PA | Palauli |
| WS | SA | Satupa’itea |
| WS | TU | Tuamasaga |
| WS | VF | Va’a-o-Fonoti |
| WS | VS | Vaisigano |
| SM | 01 | Acquaviva |
| SM | 06 | Borgo Maggiore |
| SM | 02 | Chiesanuova |
| SM | 07 | Citta di San Marino |
| SM | 03 | Domagnano |
| SM | 04 | Faetano |
| SM | 05 | Fiorentino |
| SM | 08 | Montegiardino |
| SM | 09 | Serravalle |
| ST | P | Principe |
| ST | 01 | Água Grande |
| ST | 02 | Cantagalo |
| ST | 03 | Caué |
| ST | 04 | Lembá |
| ST | 05 | Lobata |
| ST | 06 | Mé-Zóchi |
| SA | 14 | ‘Asir |
| SA | 11 | Al Bahah |
| SA | 08 | Al Hudud ash Shamaliyah |
| SA | 12 | Al Jawf |
| SA | 05 | Al Qasim |
| SA | 01 | Ar Riyad |
| SA | 06 | Ha’il |
| SA | 10 | Najran |
| SA | 07 | Tabuk |
| SA | 02 | Makkah al Mukarramah |
| SA | 03 | Al Madīnah al Munawwarah |
| SA | 04 | Ash Sharqīyah |
| SA | 09 | Jāzān |
| SN | DK | Dakar |
| SN | DB | Diourbel |
| SN | FK | Fatick |
| SN | KA | Kaolack |
| SN | KD | Kolda |
| SN | LG | Louga |
| SN | MT | Matam |
| SN | SL | Saint-Louis |
| SN | TC | Tambacounda |
| SN | TH | Thies |
| SN | ZG | Ziguinchor |
| SN | KE | Kédougou |
| SN | SE | Sédhiou |
| RS | 00 | Beograd |
| RS | 01 | Severnobački okrug |
| RS | 02 | Srednjebanatski okrug |
| RS | 03 | Severnobanatski okrug |
| RS | 04 | Južnobanatski okrug |
| RS | 05 | Zapadnobački okrug |
| RS | 06 | Južnobački okrug |
| RS | 07 | Sremski okrug |
| RS | 08 | Mačvanski okrug |
| RS | 09 | Kolubarski okrug |
| RS | 10 | Podunavski okrug |
| RS | 11 | Braničevski okrug |
| RS | 12 | Šumadijski okrug |
| RS | 13 | Pomoravski okrug |
| RS | 14 | Borski okrug |
| RS | 15 | Zaječarski okrug |
| RS | 16 | Zlatiborski okrug |
| RS | 17 | Moravički okrug |
| RS | 18 | Raški okrug |
| RS | 19 | Rasinski okrug |
| RS | 20 | Nišavski okrug |
| RS | 21 | Toplički okrug |
| RS | 22 | Pirotski okrug |
| RS | 23 | Jablanički okrug |
| RS | 24 | Pčinjski okrug |
| RS | 25 | Kosovski okrug |
| RS | 26 | Pećki okrug |
| RS | 27 | Prizrenski okrug |
| RS | 28 | Kosovsko-Mitrovački okrug |
| RS | 29 | Kosovsko-Pomoravski okrug |
| RS | KM | Kosovo-Metohija |
| RS | VO | Vojvodina |
| SC | 02 | Anse Boileau |
| SC | 03 | Anse Etoile |
| SC | 05 | Anse Royale |
| SC | 01 | Anse aux Pins |
| SC | 06 | Baie Lazare |
| SC | 07 | Baie Sainte Anne |
| SC | 08 | Beau Vallon |
| SC | 09 | Bel Air |
| SC | 10 | Bel Ombre |
| SC | 11 | Cascade |
| SC | 12 | Glacis |
| SC | 15 | La Digue |
| SC | 16 | La Riviere Anglaise |
| SC | 17 | Mont Buxton |
| SC | 18 | Mont Fleuri |
| SC | 19 | Plaisance |
| SC | 20 | Pointe La Rue |
| SC | 21 | Port Glaud |
| SC | 22 | Saint Louis |
| SC | 23 | Takamaka |
| SC | 04 | O Kap |
| SC | 13 | Grand’Anse Mahé |
| SC | 14 | Grand’Anse Praslin |
| SC | 24 | Les Mamelles |
| SC | 25 | Ros Kaiman |
| SC | 26 | Ile Perseverance I |
| SC | 27 | Ile Perseverance II |
| SL | E | Eastern |
| SL | N | Northern |
| SL | S | Southern |
| SL | W | Western |
| SL | NW | North Western |
| SG | 01 | Central Singapore |
| SG | 02 | North East |
| SG | 03 | North West |
| SG | 04 | South East |
| SG | 05 | South West |
| SK | NI | Nitriansky |
| SK | TC | Trenčiansky |
| SK | ZI | Žilinský |
| SK | BC | Banskobystrický kraj |
| SK | BL | Bratislavský kraj |
| SK | KI | Košický kraj |
| SK | PV | Prešovský kraj |
| SK | TA | Trnavský kraj |
| SI | 001 | Ajdovščina |
| SI | 002 | Beltinci |
| SI | 003 | Bled |
| SI | 004 | Bohinj |
| SI | 005 | Borovnica |
| SI | 006 | Bovec |
| SI | 007 | Brda |
| SI | 008 | Brezovica |
| SI | 009 | Brežice |
| SI | 010 | Tišina |
| SI | 011 | Celje |
| SI | 012 | Cerklje na Gorenjskem |
| SI | 013 | Cerknica |
| SI | 014 | Cerkno |
| SI | 015 | Črenšovci |
| SI | 016 | Črna na Koroškem |
| SI | 017 | Črnomelj |
| SI | 018 | Destrnik |
| SI | 019 | Divača |
| SI | 020 | Dobrepolje |
| SI | 021 | Dobrova-Polhov Gradec |
| SI | 022 | Dol pri Ljubljani |
| SI | 023 | Domžale |
| SI | 024 | Dornava |
| SI | 025 | Dravograd |
| SI | 026 | Duplek |
| SI | 027 | Gorenja vas-Poljane |
| SI | 028 | Gorišnica |
| SI | 029 | Gornja Radgona |
| SI | 030 | Gornji Grad |
| SI | 031 | Gornji Petrovci |
| SI | 032 | Grosuplje |
| SI | 033 | Šalovci |
| SI | 034 | Hrastnik |
| SI | 035 | Hrpelje-Kozina |
| SI | 036 | Idrija |
| SI | 037 | Ig |
| SI | 038 | Ilirska Bistrica |
| SI | 039 | Ivančna Gorica |
| SI | 040 | Izola |
| SI | 041 | Jesenice |
| SI | 042 | Juršinci |
| SI | 043 | Kamnik |
| SI | 044 | Kanal |
| SI | 045 | Kidričevo |
| SI | 046 | Kobarid |
| SI | 047 | Kobilje |
| SI | 048 | Kočevje |
| SI | 049 | Komen |
| SI | 050 | Koper |
| SI | 051 | Kozje |
| SI | 052 | Kranj |
| SI | 053 | Kranjska Gora |
| SI | 054 | Krško |
| SI | 055 | Kungota |
| SI | 056 | Kuzma |
| SI | 057 | Laško |
| SI | 058 | Lenart |
| SI | 059 | Lendava |
| SI | 060 | Litija |
| SI | 061 | Ljubljana |
| SI | 062 | Ljubno |
| SI | 063 | Ljutomer |
| SI | 064 | Logatec |
| SI | 065 | Loška dolina |
| SI | 066 | Loški Potok |
| SI | 067 | Luče |
| SI | 068 | Lukovica |
| SI | 069 | Majšperk |
| SI | 070 | Maribor |
| SI | 071 | Medvode |
| SI | 072 | Mengeš |
| SI | 073 | Metlika |
| SI | 074 | Mežica |
| SI | 075 | Miren-Kostanjevica |
| SI | 076 | Mislinja |
| SI | 077 | Moravče |
| SI | 078 | Moravske Toplice |
| SI | 079 | Mozirje |
| SI | 080 | Murska Sobota |
| SI | 081 | Muta |
| SI | 082 | Naklo |
| SI | 083 | Nazarje |
| SI | 084 | Nova Gorica |
| SI | 085 | Novo Mesto |
| SI | 086 | Odranci |
| SI | 087 | Ormož |
| SI | 088 | Osilnica |
| SI | 089 | Pesnica |
| SI | 090 | Piran |
| SI | 091 | Pivka |
| SI | 092 | Podčetrtek |
| SI | 093 | Podvelka |
| SI | 094 | Postojna |
| SI | 095 | Preddvor |
| SI | 096 | Ptuj |
| SI | 097 | Puconci |
| SI | 098 | Rače-Fram |
| SI | 099 | Radeče |
| SI | 100 | Radenci |
| SI | 101 | Radlje ob Dravi |
| SI | 102 | Radovljica |
| SI | 103 | Ravne na Koroškem |
| SI | 104 | Ribnica |
| SI | 105 | Rogašovci |
| SI | 106 | Rogaška Slatina |
| SI | 107 | Rogatec |
| SI | 108 | Ruše |
| SI | 109 | Semič |
| SI | 110 | Sevnica |
| SI | 111 | Sežana |
| SI | 112 | Slovenj Gradec |
| SI | 113 | Slovenska Bistrica |
| SI | 114 | Slovenske Konjice |
| SI | 115 | Starše |
| SI | 116 | Sveti Jurij ob Ščavnici |
| SI | 117 | Šenčur |
| SI | 118 | Šentilj |
| SI | 119 | Šentjernej |
| SI | 120 | Šentjur |
| SI | 121 | Škocjan |
| SI | 122 | Škofja Loka |
| SI | 123 | Škofljica |
| SI | 124 | Šmarje pri Jelšah |
| SI | 125 | Šmartno ob Paki |
| SI | 126 | Šoštanj |
| SI | 127 | Štore |
| SI | 128 | Tolmin |
| SI | 129 | Trbovlje |
| SI | 130 | Trebnje |
| SI | 131 | Tržič |
| SI | 132 | Turnišče |
| SI | 133 | Velenje |
| SI | 134 | Velike Lašče |
| SI | 135 | Videm |
| SI | 136 | Vipava |
| SI | 137 | Vitanje |
| SI | 138 | Vodice |
| SI | 139 | Vojnik |
| SI | 140 | Vrhnika |
| SI | 141 | Vuzenica |
| SI | 142 | Zagorje ob Savi |
| SI | 143 | Zavrč |
| SI | 144 | Zreče |
| SI | 146 | Železniki |
| SI | 147 | Žiri |
| SI | 148 | Benedikt |
| SI | 149 | Bistrica ob Sotli |
| SI | 150 | Bloke |
| SI | 151 | Braslovče |
| SI | 152 | Cankova |
| SI | 153 | Cerkvenjak |
| SI | 154 | Dobje |
| SI | 155 | Dobrna |
| SI | 156 | Dobrovnik |
| SI | 157 | Dolenjske Toplice |
| SI | 158 | Grad |
| SI | 159 | Hajdina |
| SI | 160 | Hoče-Slivnica |
| SI | 161 | Hodoš |
| SI | 162 | Horjul |
| SI | 163 | Jezersko |
| SI | 164 | Komenda |
| SI | 165 | Kostel |
| SI | 166 | Križevci |
| SI | 167 | Lovrenc na Pohorju |
| SI | 168 | Markovci |
| SI | 169 | Miklavž na Dravskem polju |
| SI | 170 | Mirna Peč |
| SI | 171 | Oplotnica |
| SI | 172 | Podlehnik |
| SI | 173 | Polzela |
| SI | 174 | Prebold |
| SI | 175 | Prevalje |
| SI | 176 | Razkrižje |
| SI | 177 | Ribnica na Pohorju |
| SI | 178 | Selnica ob Dravi |
| SI | 179 | Sodražica |
| SI | 180 | Solčava |
| SI | 181 | Sveta Ana |
| SI | 182 | Sveti Andraž v Slovenskih goricah |
| SI | 183 | Šempeter-Vrtojba |
| SI | 184 | Tabor |
| SI | 185 | Trnovska Vas |
| SI | 186 | Trzin |
| SI | 187 | Velika Polana |
| SI | 188 | Veržej |
| SI | 189 | Vransko |
| SI | 190 | Žalec |
| SI | 191 | Žetale |
| SI | 192 | Žirovnica |
| SI | 193 | Žužemberk |
| SI | 194 | Šmartno pri Litiji |
| SI | 195 | Apače |
| SI | 196 | Cirkulane |
| SI | 197 | Kosanjevica na Krki |
| SI | 198 | Makole |
| SI | 199 | Mokronog-Trebelno |
| SI | 200 | Poljčane |
| SI | 201 | Renče-Vogrsko |
| SI | 202 | Središče ob Dravi |
| SI | 203 | Straža |
| SI | 204 | Sveta Trojica v Slovenskih goricah |
| SI | 205 | Sveti Tomaž |
| SI | 206 | Šmarješke Toplice |
| SI | 207 | Gorje |
| SI | 208 | Log-Dragomer |
| SI | 209 | Rečica ob Savinji |
| SI | 210 | Sveti Jurij v Slovenskih goricah |
| SI | 211 | Šentrupert |
| SI | 212 | Mirna |
| SI | 213 | Ankaran |
| SB | CE | Central |
| SB | CH | Choiseul |
| SB | GU | Guadalcanal |
| SB | IS | Isabel |
| SB | MK | Makira |
| SB | ML | Malaita |
| SB | RB | Rennell and Bellona |
| SB | TE | Temotu |
| SB | WE | Western |
| SB | CT | Capital Territory (Honiara) |
| SO | AW | Awdal |
| SO | BK | Bakool |
| SO | BN | Banaadir |
| SO | BR | Bari |
| SO | BY | Bay |
| SO | GA | Galguduud |
| SO | GE | Gedo |
| SO | HI | Hiiraan |
| SO | JD | Jubbada Dhexe |
| SO | JH | Jubbada Hoose |
| SO | MU | Mudug |
| SO | NU | Nugaal |
| SO | SA | Sanaag |
| SO | SD | Shabeellaha Dhexe |
| SO | SH | Shabeellaha Hoose |
| SO | SO | Sool |
| SO | TO | Togdheer |
| SO | WO | Woqooyi Galbeed |
| ZA | EC | Eastern Cape |
| ZA | FS | Free State |
| ZA | GP | Gauteng |
| ZA | KZN | Kwa Zulu-Natal |
| ZA | LP | Limpopo |
| ZA | MP | Mpumalanga |
| ZA | NW | North West |
| ZA | NC | Northern Cape |
| ZA | WC | Western Cape |
| ES | AL | Álava |
| ES | AV | Ávila |
| ES | AB | Albacete |
| ES | A | Alicante |
| ES | AL | Almeria |
| ES | AS | Asturias |
| ES | BA | Badajoz |
| ES | IB | Baleares |
| ES | BA | Barcelona |
| ES | BU | Burgos |
| ES | CC | Cáceres |
| ES | CA | Cádiz |
| ES | CO | Córdoba |
| ES | CB | Cantabria |
| ES | CL | Castellón |
| ES | CE | Ceuta |
| ES | CR | Ciudad Real |
| ES | CU | Cuenca |
| ES | GI | Girona |
| ES | GR | Granada |
| ES | GU | Guadalajara |
| ES | H | Huelva |
| ES | HU | Huesca |
| ES | J | Jaén |
| ES | CA | La Coruña |
| ES | RI | La Rioja |
| ES | GC | Las Palmas |
| ES | LE | Leon |
| ES | MD | Madrid |
| ES | MA | Malaga |
| ES | ML | Melilla |
| ES | MU | Murcia |
| ES | NA | Navarra |
| ES | P | Palencia |
| ES | PO | Pontevedra |
| ES | SA | Salamanca |
| ES | TF | Santa Cruz de Tenerife |
| ES | SG | Segovia |
| ES | SE | Sevilla |
| ES | SO | Soria |
| ES | TE | Teruel |
| ES | TO | Toledo |
| ES | VC | Valencia |
| ES | VA | Valladolid |
| ES | ZA | Zamora |
| ES | Z | Zaragoza |
| ES | AN | Andalucía |
| ES | AR | Aragón |
| ES | B | Barcelona [Barcelona] |
| ES | BI | Bizkaia |
| ES | C | A Coruña [La Coruña] |
| ES | CM | Castilla-La Mancha |
| ES | CN | Canarias |
| ES | EX | Extremadura |
| ES | GA | Galicia [Galicia] |
| ES | L | Lleida [Lérida] |
| ES | LU | Lugo [Lugo] |
| ES | MC | “Murcia, Región de” |
| ES | NC | “Navarra, Comunidad Foral de” |
| ES | OR | Ourense [Orense] |
| ES | PV | País Vasco |
| ES | SS | Gipuzkoa |
| ES | T | Tarragona [Tarragona] |
| LK | 1 | Western Province |
| LK | 11 | Kŏl̮umpu |
| LK | 12 | Kampahā |
| LK | 13 | Kaḷuttuṟai |
| LK | 2 | Mattiya mākāṇam |
| LK | 21 | Mahanuvara |
| LK | 22 | Māttaḷai |
| LK | 23 | Nuwara Eliya |
| LK | 3 | Tĕṉ mākāṇam |
| LK | 31 | Kāli |
| LK | 32 | Māttaṛai |
| LK | 33 | Hambantota |
| LK | 4 | Vaṭakku mākāṇam |
| LK | 41 | Yāpanaya |
| LK | 42 | Kilinochchi |
| LK | 43 | Mannārama |
| LK | 44 | Vavuniyāva |
| LK | 45 | Mullaittivu |
| LK | 5 | Næ̆gĕnahira paḷāta |
| LK | 51 | Maṭṭakkaḷappu |
| LK | 52 | Ampāṟai |
| LK | 53 | Trincomalee |
| LK | 6 | Vayamba paḷāta |
| LK | 61 | Kuruṇægala |
| LK | 62 | Puttalama |
| LK | 7 | Vaṭamattiya mākāṇam |
| LK | 71 | Anurātapuram |
| LK | 72 | Polonnaruwa |
| LK | 8 | Uva Province |
| LK | 81 | Patuḷai |
| LK | 82 | Mŏṉarākalai |
| LK | 9 | Sabaragamuwa Province |
| LK | 91 | Ratnapura |
| LK | 92 | Kægalla |
| SD | RS | Al Bahr al Ahmar |
| SD | GZ | Al Jazirah |
| SD | KH | Al Khartum |
| SD | GD | Al Qadarif |
| SD | NW | An Nil al Abyad |
| SD | NB | An Nil al Azraq |
| SD | NO | Ash Shamaliyah |
| SD | DW | Gharb Darfur |
| SD | GK | Gharb Kurdufan |
| SD | DS | Janub Darfur |
| SD | KS | Janub Kurdufan |
| SD | KA | Kassala |
| SD | NR | Nahr an Nil |
| SD | DN | Shamal Darfur |
| SD | KN | Shamal Kurdufan |
| SD | SI | Sinnar |
| SD | DC | Wasaţ Dārfūr |
| SD | DE | Sharq Dārfūr |
| SR | BR | Brokopondo |
| SR | CM | Commewijne |
| SR | CR | Coronie |
| SR | MA | Marowijne |
| SR | NI | Nickerie |
| SR | PR | Para |
| SR | PM | Paramaribo |
| SR | SA | Saramacca |
| SR | SI | Sipaliwini |
| SR | WA | Wanica |
| SZ | HH | Hhohho |
| SZ | LU | Lubombo |
| SZ | MA | Manzini |
| SZ | SH | Shiselweni |
| SE | T | Örebro |
| SE | E | Östergötland |
| SE | K | Blekinge |
| SE | W | Dalama |
| SE | X | Gävleborg |
| SE | I | Gotland |
| SE | N | Halland |
| SE | Z | Jämtland |
| SE | F | Jönköping |
| SE | H | Kalmar |
| SE | G | Kronoberg |
| SE | BD | Norrbotten |
| SE | D | Södermanland |
| SE | M | Skåne |
| SE | AB | Stockholm |
| SE | C | Uppsala |
| SE | S | Värmland |
| SE | AC | Västerbotten |
| SE | Y | Västernorrland |
| SE | U | Västmanland |
| SE | O | Västra Götaland |
| CH | AG | Aargau |
| CH | AR | Appenzell Ausserrhoden |
| CH | AI | Appenzell Innerrhoden |
| CH | BL | Basel-Landschaft |
| CH | BS | Basel-Stadt |
| CH | BE | Bern |
| CH | FR | Fribourg |
| CH | GE | Genève |
| CH | GL | Glarus |
| CH | GR | Graubünden |
| CH | JU | Jura |
| CH | LU | Luzern |
| CH | NE | Neuchâtel |
| CH | NW | Nidwald |
| CH | OW | Obwald |
| CH | SH | Schaffhausen |
| CH | SZ | Schwyz |
| CH | SO | Solothurn |
| CH | SG | St. Gallen |
| CH | TG | Thurgau |
| CH | TI | Ticino |
| CH | UR | Uri |
| CH | VS | Valais |
| CH | VD | Vaud |
| CH | ZH | Zürich |
| CH | ZG | Zug |
| SY | HA | Al Hasakah |
| SY | LA | Al Ladhiqiyah |
| SY | QU | Al Qunaytirah |
| SY | RA | Ar Raqqah |
| SY | SU | As Suwayda |
| SY | DY | Dayr az Zawr |
| SY | DI | Dimashq |
| SY | HL | Halab |
| SY | HM | Hamah |
| SY | HI | Hims |
| SY | ID | Idlib |
| SY | RD | Rif Dimashq |
| SY | TA | Tartus |
| SY | DR | Dar’ā |
| TW | CHA | Changhua |
| TW | CYI | Chiayi |
| TW | CYQ | Chiayi |
| TW | HSQ | Hsinchu |
| TW | HSZ | Hsinchu |
| TW | HUA | Hualien |
| TW | ILA | Yilan |
| TW | KEE | Keelung |
| TW | KHH | Kaohsiung |
| TW | KIN | Kinmen |
| TW | LIE | Lienchiang |
| TW | MIA | Miaoli |
| TW | NAN | Nantou |
| TW | NWT | New Taipei |
| TW | PEN | Penghu |
| TW | PIF | Pingtung |
| TW | TAO | Taoyuan |
| TW | TNN | Tainan |
| TW | TPE | Taipei |
| TW | TTT | Taitung |
| TW | TXG | Taichung |
| TW | YUN | Yunlin |
| TJ | GB | Gorno-Badakhstan |
| TJ | KT | Khatlon |
| TJ | SU | Sughd |
| TJ | DU | Dushanbe |
| TJ | RA | nohiyahoi tobei jumhurí |
| TZ | 01 | Arusha |
| TZ | 02 | Dar es Salaam |
| TZ | 03 | Dodoma |
| TZ | 04 | Iringa |
| TZ | 05 | Kagera |
| TZ | 08 | Kigoma |
| TZ | 09 | Kilimanjaro |
| TZ | 12 | Lindi |
| TZ | 26 | Manyara |
| TZ | 13 | Mara |
| TZ | 14 | Mbeya |
| TZ | 16 | Morogoro |
| TZ | 17 | Mtwara |
| TZ | 18 | Mwanza |
| TZ | 06 | Pemba North |
| TZ | 10 | Pemba South |
| TZ | 19 | Pwani |
| TZ | 20 | Rukwa |
| TZ | 21 | Ruvuma |
| TZ | 22 | Shinyanga |
| TZ | 23 | Singida |
| TZ | 24 | Tabora |
| TZ | 25 | Tanga |
| TZ | 07 | Zanzibar North |
| TZ | 11 | Zanzibar South |
| TZ | 15 | Zanzibar West |
| TZ | 27 | Geita |
| TZ | 28 | Katavi |
| TZ | 29 | Njombe |
| TZ | 30 | Simiyu |
| TZ | 31 | Songwe |
| TH | 37 | Amnat Charoen |
| TH | 15 | Ang Thong |
| TH | 14 | Ayutthaya |
| TH | 10 | Bangkok |
| TH | 31 | Buriram |
| TH | 24 | Chachoengsao |
| TH | 18 | Chai Nat |
| TH | 36 | Chaiyaphum |
| TH | 22 | Chanthaburi |
| TH | 50 | Chiang Mai |
| TH | 57 | Chiang Rai |
| TH | 20 | Chon Buri |
| TH | 86 | Chumphon |
| TH | 46 | Kalasin |
| TH | 62 | Kamphaeng Phet |
| TH | 71 | Kanchanaburi |
| TH | 40 | Khon Kaen |
| TH | 81 | Krabi |
| TH | 52 | Lampang |
| TH | 51 | Lamphun |
| TH | 42 | Loei |
| TH | 16 | Lop Buri |
| TH | 58 | Mae Hong Son |
| TH | 44 | Maha Sarakham |
| TH | 49 | Mukdahan |
| TH | 26 | Nakhon Nayok |
| TH | 73 | Nakhon Pathom |
| TH | 48 | Nakhon Phanom |
| TH | 30 | Nakhon Ratchasima |
| TH | 60 | Nakhon Sawan |
| TH | 80 | Nakhon Si Thammarat |
| TH | 55 | Nan |
| TH | 96 | Narathiwat |
| TH | 39 | Nong Bua Lamphu |
| TH | 43 | Nong Khai |
| TH | 12 | Nonthaburi |
| TH | 13 | Pathum Thani |
| TH | 94 | Pattani |
| TH | 82 | Phangnga |
| TH | 93 | Phatthalung |
| TH | 56 | Phayao |
| TH | 67 | Phetchabun |
| TH | 76 | Phetchaburi |
| TH | 66 | Phichit |
| TH | 65 | Phitsanulok |
| TH | 54 | Phrae |
| TH | 83 | Phuket |
| TH | 25 | Prachin Buri |
| TH | 77 | Prachuap Khiri Khan |
| TH | 85 | Ranong |
| TH | 70 | Ratchaburi |
| TH | 21 | Rayong |
| TH | 45 | Roi Et |
| TH | 27 | Sa Kaeo |
| TH | 47 | Sakon Nakhon |
| TH | 11 | Samut Prakan |
| TH | 74 | Samut Sakhon |
| TH | 75 | Samut Songkhram |
| TH | 19 | Sara Buri |
| TH | 91 | Satun |
| TH | 17 | Sing Buri |
| TH | 33 | Sisaket |
| TH | 90 | Songkhla |
| TH | 64 | Sukhothai |
| TH | 72 | Suphan Buri |
| TH | 84 | Surat Thani |
| TH | 32 | Surin |
| TH | 63 | Tak |
| TH | 92 | Trang |
| TH | 23 | Trat |
| TH | 34 | Ubon Ratchathani |
| TH | 41 | Udon Thani |
| TH | 61 | Uthai Thani |
| TH | 53 | Uttaradit |
| TH | 95 | Yala |
| TH | 35 | Yasothon |
| TH | 38 | Bueng Kan |
| TH | S | Phatthaya |
| TL | AL | Aileu |
| TL | AN | Ainaro |
| TL | BA | Baucau |
| TL | BO | Bobonaro |
| TL | CO | Cova Lima |
| TL | DI | Dili |
| TL | ER | Ermera |
| TL | LA | Lautem |
| TL | LI | Liquica |
| TL | MT | Manatuto |
| TL | MF | Manufahi |
| TL | OE | Oecussi |
| TL | VI | Viqueque |
| TG | C | Centrale |
| TG | K | Kara |
| TG | M | Maritime |
| TG | P | Plateaux |
| TG | S | Savanes |
| TO | 02 | Ha’apai |
| TO | 04 | Tongatapu |
| TO | 05 | Vava’u |
| TO | 01 | ‘Eua |
| TO | 03 | Niuas |
| TT | ARI | Arima |
| TT | CHA | Chaguanas |
| TT | DMN | Diego Martin |
| TT | PTF | Point Fortin |
| TT | POS | Port of Spain |
| TT | PRT | Princes Town |
| TT | SFO | San Fernando |
| TT | SGE | Sangre Grande |
| TT | SIP | Siparia |
| TT | TOB | Tobago |
| TT | CTT | Couva-Tabaquite-Talparo |
| TT | MRC | Mayaro-Rio Claro |
| TT | PED | Penal-Debe |
| TT | SJL | San Juan-Laventille |
| TT | TUP | Tunapuna-Piarco |
| TN | 31 | Beja |
| TN | 13 | Ben Arous |
| TN | 23 | Bizerte |
| TN | 81 | Gabes |
| TN | 71 | Gafsa |
| TN | 32 | Jendouba |
| TN | 41 | Kairouan |
| TN | 42 | Kasserine |
| TN | 73 | Kebili |
| TN | 53 | Mahdia |
| TN | 82 | Medenine |
| TN | 52 | Monastir |
| TN | 21 | Nabeul |
| TN | 61 | Sfax |
| TN | 34 | Siliana |
| TN | 51 | Sousse |
| TN | 83 | Tataouine |
| TN | 72 | Tozeur |
| TN | 11 | Tunis |
| TN | 22 | Zaghouan |
| TN | 12 | L’Ariana |
| TN | 14 | La Manouba |
| TN | 33 | Le Kef |
| TN | 43 | Sidi Bouzid |
| TR | 01 | Adana |
| TR | 02 | Adiyaman |
| TR | 03 | Afyonkarahisar |
| TR | 04 | Agri |
| TR | 68 | Aksaray |
| TR | 05 | Amasya |
| TR | 06 | Ankara |
| TR | 07 | Antalya |
| TR | 75 | Ardahan |
| TR | 08 | Artvin |
| TR | 09 | Aydin |
| TR | 10 | Balikesir |
| TR | 74 | Bartin |
| TR | 72 | Batman |
| TR | 69 | Bayburt |
| TR | 11 | Bilecik |
| TR | 12 | Bingol |
| TR | 13 | Bitlis |
| TR | 14 | Bolu |
| TR | 15 | Burdur |
| TR | 16 | Bursa |
| TR | 17 | Canakkale |
| TR | 18 | Cankiri |
| TR | 19 | Corum |
| TR | 20 | Denizli |
| TR | 21 | Diyarbakir |
| TR | 81 | Duzce |
| TR | 22 | Edirne |
| TR | 23 | Elazig |
| TR | 24 | Erzincan |
| TR | 25 | Erzurum |
| TR | 26 | Eskisehir |
| TR | 27 | Gaziantep |
| TR | 28 | Giresun |
| TR | 29 | Gumushane |
| TR | 30 | Hakkari |
| TR | 31 | Hatay |
| TR | 76 | Igdir |
| TR | 32 | Isparta |
| TR | 34 | Istanbul |
| TR | 35 | Izmir |
| TR | 46 | Kahramanmaras |
| TR | 78 | Karabuk |
| TR | 70 | Karaman |
| TR | 36 | Kars |
| TR | 37 | Kastamonu |
| TR | 38 | Kayseri |
| TR | 79 | Kilis |
| TR | 71 | Kirikkale |
| TR | 39 | Kirklareli |
| TR | 40 | Kirsehir |
| TR | 41 | Kocaeli |
| TR | 42 | Konya |
| TR | 43 | Kutahya |
| TR | 44 | Malatya |
| TR | 45 | Manisa |
| TR | 47 | Mardin |
| TR | 33 | Mersin |
| TR | 48 | Mugla |
| TR | 49 | Mus |
| TR | 50 | Nevsehir |
| TR | 51 | Nigde |
| TR | 52 | Ordu |
| TR | 80 | Osmaniye |
| TR | 53 | Rize |
| TR | 54 | Sakarya |
| TR | 55 | Samsun |
| TR | 63 | Sanliurfa |
| TR | 56 | Siirt |
| TR | 57 | Sinop |
| TR | 73 | Sirnak |
| TR | 58 | Sivas |
| TR | 59 | Tekirdag |
| TR | 60 | Tokat |
| TR | 61 | Trabzon |
| TR | 62 | Tunceli |
| TR | 64 | Usak |
| TR | 65 | Van |
| TR | 77 | Yalova |
| TR | 66 | Yozgat |
| TR | 67 | Zonguldak |
| TM | A | Ahal Welayaty |
| TM | B | Balkan Welayaty |
| TM | D | Dashhowuz Welayaty |
| TM | L | Lebap Welayaty |
| TM | M | Mary Welayaty |
| TM | S | Aşgabat |
| TV | FUN | Funafuti |
| TV | NMG | Nanumanga |
| TV | NMA | Nanumea |
| TV | NIT | Niutao |
| TV | NUI | Nui |
| TV | NKF | Nukufetau |
| TV | NKL | Nukulaelae |
| TV | VAI | Vaitupu |
| UG | 301 | Adjumani |
| UG | 302 | Apac |
| UG | 303 | Arua |
| UG | 201 | Bugiri |
| UG | 401 | Bundibugyo |
| UG | 402 | Bushenyi |
| UG | 202 | Busia |
| UG | 304 | Gulu |
| UG | 403 | Hoima |
| UG | 203 | Iganga |
| UG | 204 | Jinja |
| UG | 404 | Kabale |
| UG | 405 | Kabarole |
| UG | 213 | Kaberamaido |
| UG | 101 | Kalangala |
| UG | 102 | Kampala |
| UG | 205 | Kamuli |
| UG | 413 | Kamwenge |
| UG | 414 | Kanungu |
| UG | 206 | Kapchorwa |
| UG | 406 | Kasese |
| UG | 207 | Katakwi |
| UG | 112 | Kayunga |
| UG | 407 | Kibaale |
| UG | 103 | Kiboga |
| UG | 408 | Kisoro |
| UG | 305 | Kitgum |
| UG | 306 | Kotido |
| UG | 208 | Kumi |
| UG | 415 | Kyenjojo |
| UG | 307 | Lira |
| UG | 104 | Luwero |
| UG | 105 | Masaka |
| UG | 409 | Masindi |
| UG | 214 | Mayuge |
| UG | 209 | Mbale |
| UG | 410 | Mbarara |
| UG | 308 | Moroto |
| UG | 309 | Moyo |
| UG | 106 | Mpigi |
| UG | 107 | Mubende |
| UG | 108 | Mukono |
| UG | 311 | Nakapiripirit |
| UG | 109 | Nakasongola |
| UG | 310 | Nebbi |
| UG | 411 | Ntungamo |
| UG | 312 | Pader |
| UG | 210 | Pallisa |
| UG | 110 | Rakai |
| UG | 412 | Rukungiri |
| UG | 111 | Sembabule |
| UG | 215 | Sironko |
| UG | 211 | Soroti |
| UG | 212 | Tororo |
| UG | 113 | Wakiso |
| UG | 313 | Yumbe |
| UG | 114 | Lyantonde |
| UG | 115 | Mityana |
| UG | 116 | Nakaseke |
| UG | 117 | Buikwe |
| UG | 118 | Bukomansibi |
| UG | 119 | Butambala |
| UG | 120 | Buvuma |
| UG | 121 | Gomba |
| UG | 122 | Kalungu |
| UG | 123 | Kyankwanzi |
| UG | 124 | Lwengo |
| UG | 125 | Kyotera |
| UG | 126 | Kasanda |
| UG | 216 | Amuria |
| UG | 217 | Budaka |
| UG | 218 | Bududa |
| UG | 219 | Bukedea |
| UG | 220 | Bukwo |
| UG | 221 | Butaleja |
| UG | 222 | Kaliro |
| UG | 223 | Manafwa |
| UG | 224 | Namutumba |
| UG | 225 | Bulambuli |
| UG | 226 | Buyende |
| UG | 227 | Kibuku |
| UG | 228 | Kween |
| UG | 229 | Luuka |
| UG | 230 | Namayingo |
| UG | 231 | Ngora |
| UG | 232 | Serere |
| UG | 233 | Butebo |
| UG | 234 | Namisindwa |
| UG | 235 | Bugweri |
| UG | 236 | Kapelebyong |
| UG | 237 | Kalaki |
| UG | 314 | Abim |
| UG | 315 | Amolatar |
| UG | 316 | Amuru |
| UG | 317 | Dokolo |
| UG | 318 | Kaabong |
| UG | 319 | Koboko |
| UG | 320 | Maracha |
| UG | 321 | Oyam |
| UG | 322 | Agago |
| UG | 323 | Alebtong |
| UG | 324 | Amudat |
| UG | 325 | Kole |
| UG | 326 | Lamwo |
| UG | 327 | Napak |
| UG | 328 | Nwoya |
| UG | 329 | Otuke |
| UG | 330 | Zombo |
| UG | 331 | Omoro |
| UG | 332 | Pakwach |
| UG | 333 | Kwania |
| UG | 334 | Nabilatuk |
| UG | 335 | Karenga |
| UG | 336 | Madi-Okollo |
| UG | 337 | Obongi |
| UG | 416 | Buliisa |
| UG | 417 | Ibanda |
| UG | 418 | Isingiro |
| UG | 419 | Kiruhura |
| UG | 420 | Buhweju |
| UG | 421 | Kiryandongo |
| UG | 422 | Kyegegwa |
| UG | 423 | Mitooma |
| UG | 424 | Ntoroko |
| UG | 425 | Rubirizi |
| UG | 426 | Sheema |
| UG | 427 | Kagadi |
| UG | 428 | Kakumiro |
| UG | 429 | Rubanda |
| UG | 430 | Bunyangabu |
| UG | 431 | Rukiga |
| UG | 432 | Kikuube |
| UG | 433 | Kazo |
| UG | 434 | Kitagwenda |
| UG | 435 | Rwampara |
| UG | C | Central |
| UG | E | Eastern |
| UG | N | Northern |
| UG | W | Western |
| UA | 40 | Sevastopol |
| UA | 05 | Vinnytska oblast |
| UA | 07 | Volynska oblast |
| UA | 09 | Luhanska oblast |
| UA | 12 | Dnipropetrovska oblast |
| UA | 14 | Donetska oblast |
| UA | 18 | Zhytomyrska oblast |
| UA | 21 | Zakarpatska oblast |
| UA | 23 | Zaporizka oblast |
| UA | 26 | Ivano-Frankivska oblast |
| UA | 30 | Kyiv |
| UA | 32 | Kyivska oblast |
| UA | 35 | Kirovohradska oblast |
| UA | 43 | Avtonomna Respublika Krym |
| UA | 46 | Lvivska oblast |
| UA | 48 | Mykolaivska oblast |
| UA | 51 | Odeska oblast |
| UA | 53 | Poltavska oblast |
| UA | 56 | Rivnenska oblast |
| UA | 59 | Sumska oblast |
| UA | 61 | Ternopilska oblast |
| UA | 63 | Kharkivska oblast |
| UA | 65 | Khersonska oblast |
| UA | 68 | Khmelnytska oblast |
| UA | 71 | Cherkaska oblast |
| UA | 74 | Chernihivska oblast |
| UA | 77 | Chernivetska oblast |
| AE | AJ | ‘Ajman |
| AE | AZ | Abu Zaby |
| AE | FU | Al Fujayrah |
| AE | SH | Ash Shariqah |
| AE | DU | Dubayy |
| AE | RK | R’as al Khaymah |
| AE | UQ | Umm al Qaywayn |
| GB | ABE | Aberdeen City |
| GB | ABD | Aberdeenshire |
| GB | ANS | Angus |
| GB | AGB | Argyll and Bute |
| GB | BDG | Barking and Dagenham |
| GB | BNE | Barnet |
| GB | BNS | Barnsley |
| GB | BAS | Bath and North East Somerset |
| GB | BDF | Bedfordshire |
| GB | BFS | Belfast |
| GB | BEX | Bexley |
| GB | BIR | Birmingham |
| GB | BBD | Blackburn with Darwen |
| GB | BPL | Blackpool |
| GB | BGW | Blaenau Gwent |
| GB | BOL | Bolton |
| GB | BRC | Bracknell Forest |
| GB | BRD | Bradford |
| GB | BEN | Brent |
| GB | BGE | Bridgend [Pen-y-bont ar Ogwr GB-POG] |
| GB | BNH | Brighton and Hove |
| GB | BST | “Bristol, City of” |
| GB | BRY | Bromley |
| GB | BKM | Buckinghamshire |
| GB | BUR | Bury |
| GB | CAY | Caerphilly [Caerffili GB-CAF] |
| GB | CLD | Calderdale |
| GB | CAM | Cambridgeshire |
| GB | CMD | Camden |
| GB | CRF | Cardiff [Caerdydd GB-CRD] |
| GB | CMN | Carmarthenshire [Sir Gaerfyrddin GB-GFY] |
| GB | CBF | Central Bedfordshire |
| GB | CGN | Ceredigion [Sir Ceredigion] |
| GB | CHE | Cheshire East |
| GB | CHW | Cheshire West and Chester |
| GB | CLK | Clackmannanshire |
| GB | CWY | Conwy |
| GB | CON | Cornwall |
| GB | COV | Coventry |
| GB | CRY | Croydon |
| GB | CMA | Cumbria |
| GB | DAL | Darlington |
| GB | DEN | Denbighshire [Sir Ddinbych GB-DDB] |
| GB | DBY | Derbyshire |
| GB | DER | Derby |
| GB | DEV | Devon |
| GB | DNC | Doncaster |
| GB | DOR | Dorset |
| GB | DUD | Dudley |
| GB | DGY | Dumfries and Galloway |
| GB | DND | Dundee City |
| GB | DUR | Durham |
| GB | EAL | Ealing |
| GB | EAY | East Ayrshire |
| GB | EDU | East Dunbartonshire |
| GB | ELN | East Lothian |
| GB | ERW | East Renfrewshire |
| GB | ERY | East Riding of Yorkshire |
| GB | ESX | East Sussex |
| GB | EDH | “Edinburgh, City of” |
| GB | ELS | Eilean Siar |
| GB | ENF | Enfield |
| GB | ESS | Essex |
| GB | FAL | Falkirk |
| GB | FIF | Fife |
| GB | FLN | Flintshire [Sir y Fflint GB-FFL] |
| GB | GAT | Gateshead |
| GB | GLG | Glasgow City |
| GB | GLS | Gloucestershire |
| GB | GRE | Greenwich |
| GB | GWN | Gwynedd |
| GB | HCK | Hackney |
| GB | HAL | Halton |
| GB | HMF | Hammersmith and Fulham |
| GB | HAM | Hampshire |
| GB | HRY | Haringey |
| GB | HRW | Harrow |
| GB | HPL | Hartlepool |
| GB | HAV | Havering |
| GB | HEF | “Herefordshire, County of” |
| GB | HRT | Hertfordshire |
| GB | HLD | Highland |
| GB | HIL | Hillingdon |
| GB | HNS | Hounslow |
| GB | IVC | Inverclyde |
| GB | AGY | Isle of Anglesey [Sir Ynys Môn GB-YNM] |
| GB | IOW | Isle of Wight |
| GB | ISL | Islington |
| GB | KEC | Kensington and Chelsea |
| GB | KEN | Kent |
| GB | KHL | “Kingston upon Hull, City of” |
| GB | KTT | Kingston upon Thames |
| GB | KIR | Kirklees |
| GB | KWL | Knowsley |
| GB | LBH | Lambeth |
| GB | LAN | Lancashire |
| GB | LDS | Leeds |
| GB | LEC | Leicestershire |
| GB | LCE | Leicester |
| GB | LEW | Lewisham |
| GB | LIN | Lincolnshire |
| GB | LIV | Liverpool |
| GB | LND | “London, City of” |
| GB | LUT | Luton |
| GB | MAN | Manchester |
| GB | MDW | Medway |
| GB | MTY | Merthyr Tydfil [Merthyr Tudful GB-MTU] |
| GB | MRT | Merton |
| GB | MDB | Middlesbrough |
| GB | MLN | Midlothian |
| GB | MIK | Milton Keynes |
| GB | MON | Monmouthshire [Sir Fynwy GB-FYN] |
| GB | MRY | Moray |
| GB | NTL | Neath Port Talbot [Castell-nedd Port Talbot GB-CTL] |
| GB | NET | Newcastle upon Tyne |
| GB | NWM | Newham |
| GB | NWP | Newport [Casnewydd GB-CNW] |
| GB | NFK | Norfolk |
| GB | NAY | North Ayrshire |
| GB | NEL | North East Lincolnshire |
| GB | NLK | North Lanarkshire |
| GB | NLN | North Lincolnshire |
| GB | NSM | North Somerset |
| GB | NTY | North Tyneside |
| GB | NYK | North Yorkshire |
| GB | NTH | Northamptonshire |
| GB | NBL | Northumberland |
| GB | NTT | Nottinghamshire |
| GB | NGM | Nottingham |
| GB | OLD | Oldham |
| GB | ORK | Orkney Islands |
| GB | OXF | Oxfordshire |
| GB | PEM | Pembrokeshire [Sir Benfro GB-BNF] |
| GB | PKN | Perth and Kinross |
| GB | PTE | Peterborough |
| GB | PLY | Plymouth |
| GB | POR | Portsmouth |
| GB | POW | Powys |
| GB | RDG | Reading |
| GB | RDB | Redbridge |
| GB | RCC | Redcar and Cleveland |
| GB | RFW | Renfrewshire |
| GB | RCT | “Rhondda, Cynon, Taff [Rhondda, Cynon,Taf]” |
| GB | RIC | Richmond upon Thames |
| GB | RCH | Rochdale |
| GB | ROT | Rotherham |
| GB | RUT | Rutland |
| GB | SLF | Salford |
| GB | SAW | Sandwell |
| GB | SCB | “Scottish Borders, The” |
| GB | SFT | Sefton |
| GB | SHF | Sheffield |
| GB | ZET | Shetland Islands |
| GB | SHR | Shropshire |
| GB | SLG | Slough |
| GB | SOL | Solihull |
| GB | SOM | Somerset |
| GB | SAY | South Ayrshire |
| GB | SGC | South Gloucestershire |
| GB | SLK | South Lanarkshire |
| GB | STY | South Tyneside |
| GB | STH | Southampton |
| GB | SOS | Southend-on-Sea |
| GB | SWK | Southwark |
| GB | SHN | St. Helens |
| GB | STS | Staffordshire |
| GB | STG | Stirling |
| GB | SKP | Stockport |
| GB | STT | Stockton-on-Tees |
| GB | STE | Stoke-on-Trent |
| GB | SFK | Suffolk |
| GB | SND | Sunderland |
| GB | SRY | Surrey |
| GB | STN | Sutton |
| GB | SWA | Swansea [Abertawe GB-ATA] |
| GB | SWD | Swindon |
| GB | TAM | Tameside |
| GB | TFW | Telford and Wrekin |
| GB | THR | Thurrock |
| GB | TOB | Torbay |
| GB | TOF | Torfaen [Tor-faen] |
| GB | TWH | Tower Hamlets |
| GB | TRF | Trafford |
| GB | VGL | “Vale of Glamorgan, The [Bro Morgannwg GB-BMG]” |
| GB | WKF | Wakefield |
| GB | WLL | Walsall |
| GB | WFT | Waltham Forest |
| GB | WND | Wandsworth |
| GB | WRT | Warrington |
| GB | WAR | Warwickshire |
| GB | WBK | West Berkshire |
| GB | WDU | West Dunbartonshire |
| GB | WLN | West Lothian |
| GB | WSX | West Sussex |
| GB | WSM | Westminster |
| GB | WGN | Wigan |
| GB | WIL | Wiltshire |
| GB | WNM | Windsor and Maidenhead |
| GB | WRL | Wirral |
| GB | WOK | Wokingham |
| GB | WLV | Wolverhampton |
| GB | WOR | Worcestershire |
| GB | WRX | Wrexham [Wrecsam GB-WRC] |
| GB | YOR | York |
| GB | ABC | “Armagh City, Banbridge and Craigavon” |
| GB | AND | Ards and North Down |
| GB | ANN | Antrim and Newtownabbey |
| GB | BCP | “Bournemouth, Christchurch and Poole” |
| GB | CCG | Causeway Coast and Glens |
| GB | DRS | Derry and Strabane |
| GB | FMO | Fermanagh and Omagh |
| GB | IOS | Isles of Scilly |
| GB | LBC | Lisburn and Castlereagh |
| GB | MEA | Mid and East Antrim |
| GB | MUL | Mid-Ulster |
| GB | NMD | “Newry, Mourne and Down” |
| UM | 81 | Baker Island |
| UM | 84 | Howland Island |
| UM | 86 | Jarvis Island |
| UM | 67 | Johnston Atoll |
| UM | 89 | Kingman Reef |
| UM | 76 | Navassa Island |
| UM | 95 | Palmyra Atoll |
| UM | 79 | Wake Island |
| UM | 71 | Midway Islands |
| UY | AR | Artigas |
| UY | CA | Canelones |
| UY | CL | Cerro Largo |
| UY | CO | Colonia |
| UY | DU | Durazno |
| UY | FS | Flores |
| UY | FD | Florida |
| UY | LA | Lavalleja |
| UY | MA | Maldonado |
| UY | MO | Montevideo |
| UY | PA | Paysandu |
| UY | RN | Rio Negro |
| UY | RV | Rivera |
| UY | RO | Rocha |
| UY | SA | Salto |
| UY | SJ | San Jose |
| UY | SO | Soriano |
| UY | TA | Tacuarembo |
| UY | TT | Treinta y Tres |
| UZ | AN | Andijon |
| UZ | BU | Buxoro |
| UZ | FA | Farg’ona |
| UZ | JI | Jizzax |
| UZ | NG | Namangan |
| UZ | NW | Navoiy |
| UZ | QA | Qashqadaryo |
| UZ | QR | Qoraqalpog’iston Republikasi |
| UZ | SA | Samarqand |
| UZ | SI | Sirdaryo |
| UZ | SU | Surxondaryo |
| UZ | TK | Toshkent City |
| UZ | TO | Toshkent Region |
| UZ | XO | Xorazm |
| VU | MAP | Malampa |
| VU | PAM | Penama |
| VU | SAM | Sanma |
| VU | SEE | Shefa |
| VU | TAE | Tafea |
| VU | TOB | Torba |
| VE | Z | Amazonas |
| VE | B | Anzoategui |
| VE | C | Apure |
| VE | D | Aragua |
| VE | E | Barinas |
| VE | F | Bolivar |
| VE | G | Carabobo |
| VE | H | Cojedes |
| VE | Y | Delta Amacuro |
| VE | W | Dependencias Federales |
| VE | I | Falcon |
| VE | J | Guarico |
| VE | K | Lara |
| VE | L | Merida |
| VE | M | Miranda |
| VE | N | Monagas |
| VE | O | Nueva Esparta |
| VE | P | Portuguesa |
| VE | R | Sucre |
| VE | S | Tachira |
| VE | T | Trujillo |
| VE | U | Yaracuy |
| VE | V | Zulia |
| VE | A | Distrito Capital |
| VE | X | La Guaira |
| VN | 44 | An Giang |
| VN | 54 | Bac Giang |
| VN | 53 | Bac Kan |
| VN | 55 | Bac Lieu |
| VN | 56 | Bac Ninh |
| VN | 50 | Ben Tre |
| VN | 57 | Binh Duong |
| VN | 58 | Binh Phuoc |
| VN | 40 | Binh Thuan |
| VN | 59 | Ca Mau |
| VN | CT | Can Tho |
| VN | 04 | Cao Bang |
| VN | DN | Da Nang |
| VN | 30 | Gia Lai |
| VN | 03 | Ha Giang |
| VN | 63 | Ha Nam |
| VN | HN | Ha Noi |
| VN | 23 | Ha Tinh |
| VN | 61 | Hai Duong |
| VN | HP | Hai Phong |
| VN | 73 | Hau Giang |
| VN | 14 | Hoa Binh |
| VN | 66 | Hung Yen |
| VN | 01 | Lai Châu |
| VN | 02 | Lào Cai |
| VN | 05 | Sơn La |
| VN | 06 | Yên Bái |
| VN | 07 | Tuyên Quang |
| VN | 09 | Lạng Sơn |
| VN | 13 | Quảng Ninh |
| VN | 18 | Ninh Bình |
| VN | 20 | Thái Bình |
| VN | 21 | Thanh Hóa |
| VN | 22 | Nghệ An |
| VN | 24 | Quảng Bình |
| VN | 25 | Quảng Trị |
| VN | 26 | Thừa Thiên-Huế |
| VN | 27 | Quảng Nam |
| VN | 28 | Kon Tum |
| VN | 29 | Quảng Ngãi |
| VN | 31 | Bình Định |
| VN | 32 | Phú Yên |
| VN | 33 | Đắk Lắk |
| VN | 34 | Khánh Hòa |
| VN | 35 | Lâm Đồng |
| VN | 36 | Ninh Thuận |
| VN | 37 | Tây Ninh |
| VN | 39 | Đồng Nai |
| VN | 41 | Long An |
| VN | 43 | Bà Rịa - Vũng Tàu |
| VN | 45 | Đồng Tháp |
| VN | 46 | Tiền Giang |
| VN | 47 | Kiến Giang |
| VN | 49 | Vĩnh Long |
| VN | 51 | Trà Vinh |
| VN | 52 | Sóc Trăng |
| VN | 67 | Nam Định |
| VN | 68 | Phú Thọ |
| VN | 69 | Thái Nguyên |
| VN | 70 | Vĩnh Phúc |
| VN | 71 | Điện Biên |
| VN | 72 | Đắk Nông |
| VN | SG | Hồ Chí Minh |
| WF | AL | Alo |
| WF | SG | Sigave |
| WF | UV | Uvea |
| YE | AB | Abyan |
| YE | DA | Ad Dali |
| YE | AD | Adan |
| YE | BA | Al Bayda |
| YE | HU | Al Hudaydah |
| YE | JA | Al Jawf |
| YE | MR | Al Mahrah |
| YE | MW | Al Mahwit |
| YE | AM | Amran |
| YE | DH | Dhamar |
| YE | HD | Hadramawt |
| YE | HJ | Hajjah |
| YE | IB | Ibb |
| YE | LA | Lahij |
| YE | MA | Ma’rib |
| YE | SD | Sa’dah |
| YE | SN | San’a |
| YE | SH | Shabwah |
| YE | TA | Ta’izz |
| YE | RA | Raymah |
| YE | SA | Amānat al ‘Āşimah [city] |
| YE | SU | Arkhabīl Suquţrá |
| ZM | 02 | Central |
| ZM | 08 | Copperbelt |
| ZM | 03 | Eastern |
| ZM | 04 | Luapula |
| ZM | 09 | Lusaka |
| ZM | 06 | North-Western |
| ZM | 05 | Northern |
| ZM | 07 | Southern |
| ZM | 01 | Western |
| ZM | 10 | Muchinga |
| ZW | BU | Bulawayo |
| ZW | HA | Harare |
| ZW | MA | Manicaland |
| ZW | MC | Mashonaland Central |
| ZW | ME | Mashonaland East |
| ZW | MW | Mashonaland West |
| ZW | MV | Masvingo |
| ZW | MN | Matabeleland North |
| ZW | MS | Matabeleland South |
| ZW | MI | Midlands |
| BQ | BO | Boneiru |
| BQ | SA | Saba |
| BQ | SE | Sint Eustatius |
| SS | BN | Northern Bahr el Ghazal |
| SS | BW | Western Bahr el Ghazal |
| SS | EC | Central Equatoria |
| SS | EE | Eastern Equatoria |
| SS | EW | Western Equatoria |
| SS | JG | Jonglei |
| SS | LK | Lakes |
| SS | NU | Upper Nile |
| SS | UY | Unity |
| SS | WR | Warrap |
### CS-Cart
The CS-Cart plugin integrates Payneteasy payment processing with the [CS-Cart](https://www.cs-cart.com/) e-commerce platform. It ships as a standard CS-Cart addon (module id `payneteasy`, display name “Paynet Easy Payment”) that registers a new payment processor in the store’s admin panel, so shop administrators can accept card payments through Payneteasy without writing custom code.
A live example of the checkout flow produced by this plugin can be seen on the [CS-Cart demo shop](https://cscart.codetime.net/).
#### Source code
The plugin source is published on Git Hub at [payneteasy/php-plugin-cscart](https://github.com/payneteasy/php-plugin-cscart). The repository contains the addon files under `app/addons/payneteasy` (install/uninstall logic, the payment processor registration, and language files) together with the corresponding `design` templates for the CS-Cart storefront and admin area.
### Currency Codes
| Currency code | Description |
|-----------------|-----------------------------------------|
| AED | United Arab Emirates dirham |
| ALL | Albanian lek |
| AMD | Armenian dram |
| ARS | Argentine peso |
| AUD | Australian dollar |
| AZN | Azerbaijani manat |
| BAM | Bosnia and Herzegovina convertible mark |
| BDT | Bangladeshi taka |
| BGN | Bulgarian lev (obsolete) |
| BHD | Bahraini dinar |
| BIF | Burundian franc |
| BOB | Bolivian boliviano |
| BRL | Brazilian real |
| BWP | Botswana pula |
| BYN | Belarusian ruble |
| CAD | Canadian dollar |
| CDF | Congolese franc |
| CHF | Swiss franc |
| CLP | Chilean peso |
| CNY | Chinese yuan |
| COP | Colombian peso |
| CRC | Costa Rican colón |
| CVE | Cape Verdean escudo |
| CZK | Czech koruna |
| DKK | Danish krone |
| DJF | Djiboutian franc |
| DLS | DLS Loyalty program |
| DOP | Dominican peso |
| DZD | Algerian dinar |
| EGP | Egyptian pound |
| ERN | Eritrean nakfa |
| ETB | Ethiopian birr |
| EUR | Euro |
| FIM | Finnish markka (obsolete) |
| GBP | Pound sterling |
| GEL | Georgian lari |
| GHS | Ghanaian cedi |
| GMD | Gambian dalasi |
| GNF | Guinean franc |
| GTQ | Guatemalan quetzal |
| HKD | Hong Kong dollar |
| HNL | Honduran lempira |
| HRK | Croatian kuna (obsolete) |
| HUF | Hungarian forint |
| IDR | Indonesian rupiah |
| ILS | Israeli new shekel |
| INR | Indian rupee |
| IRR | Iranian rial |
| ISK | Icelandic króna |
| JOD | Jordanian dinar |
| JPY | Japanese yen |
| KES | Kenyan shilling |
| KGS | Kyrgyzstani som |
| KHR | Cambodian riel |
| KMF | Comoro franc |
| Won | Korean Republic Won |
| KWD | Kuwaiti dinar |
| KZT | Kazakhstani tenge |
| LAK | Lao kip |
| LKR | Sri Lankan rupee |
| LSL | Lesotho loti |
| MAD | Moroccan dirham |
| MDL | Moldovan leu |
| MGA | Malagasy ariary |
| MKD | Macedonian denar |
| MMK | Myanmar kyat |
| MNT | Mongolian tögrög |
| MRU | Mauritanian ouguiya |
| MUR | Mauritian rupee |
| MWK | Malawian kwacha |
| MXN | Mexican peso |
| MYR | Malaysian ringgit |
| MZN | Mozambican metical |
| NAD | Namibian dollar |
| NGN | Nigerian naira |
| NIO | Nicaraguan córdoba |
| NOK | Norwegian krone |
| NZD | New Zealand dollar |
| OMR | Omani rial |
| PAB | Panamanian balboa |
| PEN | Peruvian sol |
| PHP | Philippine peso |
| PKR | Pakistani rupee |
| PLN | Polish złoty |
| PYG | Paraguayan guaraní |
| QAR | Qatari riyal |
| RON | Romanian leu |
| RSD | Serbian dinar |
| RUB | Russian ruble |
| RWF | Rwandan franc |
| SAR | Saudi riyal |
| SCR | Seychelles rupee |
| SEK | Swedish krona |
| SGD | Singapore dollar |
| SHP | Saint Helena pound |
| SLE | Sierra Leonean leone |
| SRD | Surinamese dollar |
| STN | São Tomé and Príncipe dobra |
| SZL | Eswatini lilangeni |
| THB | Thai baht |
| TJS | Tajikistani somoni |
| TMT | Turkmenistani manat |
| TND | Tunisian dinar |
| TRY | Turkish lira |
| TWD | Taiwan dollar |
| TZS | Tanzanian shilling |
| UAH | Ukrainian hryvnia |
| UGX | Ugandan Shilling |
| USD | United States Dollar |
| UYU | Uruguayan peso |
| UZS | Uzbekistani som |
| VES | Venezuelan bolívar soberano |
| VND | Vietnamese dong |
| WMZ | Web Money WMZ (USD) |
| XAF | Central African CFA franc |
| XOF | West African CFA franc |
| ZAR | South African rand |
| ZMW | Zambian kwacha |
| BTC | Bitcoin |
| μBTC | Micro Bitcoin |
| USDT | Tether (stablecoin) |
| UNS | Unspecified currency (XXX) |
### Data migration
Sensitive information, such as cardholder data, must be encrypted for PCI-compliant migration. Encryption is made with Payneteasy PGP key.
After [importing](https://www.gnupg.org/gph/en/manual.html#AEN84) Payneteasy PGP key, run the following command to encrypt the files before sending. file_name.gpg will be created:
```text
gpg --encrypt --recipient 3C7266AE file_name
```
Payneteasy Public PGP Key
Key ID: 91D14F90
Key type: RSA
Key size: 4096 bits
Fingerprint: C519 7432 AF07 595A C081 3B83 3501 1DD3 CBC2 E0AB
User ID: Payneteasy Import Key (PCI) <[security@Payneteasy.ru](mailto:security@Payneteasy.ru)>
```http
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: GnuPG v2.0.22 (GNU/Linux)
mQINBGLNircBEADNI7fzBBc2NyhhzKGb1gI94ASwNqA37dxPaC8bW1hxThaZV0Aj
jPc1EbMT9UdSjJgHZafvAqYo0EUfJqCS1BFnhjTrHiWWBr1dKQ35dMkUB4UWmius
vungosQeFgAy70eY4MS+2r05DYaBylHHhc/0TZ+v0UOaQp8ch2Uu2C6N7wYT97nV
DC0373StsON36m6k1pXLYuTSzXX9ZgZlLYvK1gyItvBqziT7AsSHeGFFjCFygcCL
i3qrmT2S4JBDXQTDaSCWG36aGTerMvkGlwixnpj6nw1E6GJsApQNY7qahn2rY3UK
40Fk7BniHLbFmR4AK5RvDWNTgu3jDdc1z9dS/6n3beM9HExly3TjpmlZDa1CxhtH
W3o69m/3BbzLOjgW6XQX1QoCjuv1ejw6Hm1b5dphyab2xXfEXS40jghuTKTMK7TN
gAsOn8siD4zTedcWdo4rUUX/WATtyRAyFBDLzORFxj4iRezGda1XfTOIgRqPc/3U
ggQhOT6BQuevdtuHjdSNY36TEJHOPi28xMOPMMpMVA5nPBHX/L+I6Z8Z9/pGDZPa
mQwlg5XebtL2t3AakGQ8goobImavQrNgDPQU+hf3maNAkBzKirqLVcAKjqG/KX7v
AMNUzzXCRqc/yGEobJuSa0wTpf2pJhHqExrAgbn3FEBiu42kY/wE20jyLQARAQAB
tDRQYXluZXRlYXN5IEltcG9ydCBLZXkgKFBDSSkgPHNlY3VyaXR5QHBheW5ldGVh
c3kucnU+iQI/BBMBAgApBQJizYq3AhsDBQkDwmcABwsJCAcDAgEGFQgCCQoLBBYC
AwECHgECF4AACgkQNQEd08vC4KubdA/9G0okz/MOp6Nz7DE2u7Hz0OVoP5OMHQ+U
TdXINlYG0PWJGricF5ohw5jYp/iwgumAb9lXJBc0/h3LZBemW/H0/HCID+wFJT6p
kSoQ2ZGKL37MRdJ6kf9H+VMjGJYS0VOJoj1xWiwUhBjmjeWCAGx88Ovej9IzZsaO
F9hCgsB/PiTm95wdqpwEfh0Cy+C5r03PoWOsa8v4bpMwl3PaNxifaD+uorJX4kOF
EvGIOkrm3o1C6gkZJR2f6RLnazDFlW0KmXUOik1MEosKYCprY2Bk3wBZ0GskyLlY
jcKppVdzfeX66vYUlczR57mlk3GSZzCQHl5fBFoX+yUY+IiowRVqjmneFP6rv9MY
Csvcl/2vdJ8Ou4pyRmRcxJiYhoNSxowWTenbhj40KHUfw7YH3/VLY2UI/LBedEMF
Dx0CqtHSNVogeb5RzzIbhySeXAut79In8AAsvtNT/OMF5ZrZtlNBi6wqZO/invgv
UkdCngSL0+TZAOySwfR0iNZaZJmZ/DfrBuP9p82HZRyK7X9GB/5Ziqs8WStOIzJr
2iQVB9TCKIrE7kWHFxA7HNzfWYgWU32lx/2R+0cH4zwuhFH2rKfrBR6Ekgl8F0+m
tuYqMMBCagF0U6OhFqTtTiQ3cz1A8inNlVkVv9AHI/2Rl5w9hRb88139TtV7aeK2
jbYLHaIwmZC5Ag0EYs2KtwEQAMwaMSjHenq5rU/vVNhhisKKvrzrzHtRFiSnshs8
cWWtr2hyAVRb+loZa5trBs6pal/X+V/fAm7LWBSjt0z1gyZfgamf0PHvmWl5JHiK
O6x22qYLS/F4O4d/tDwUPdPJPx/FXYu/q50B4IsJ0zfoKW2Zwp9hCUoY67EM+8c+
NF5pTqbZ8Fp7zM1oHIkhYRga2qXRW5lxhC8Xojc/nZp65qwW+r2JVlBECa/A2OL8
FsMMObkdgE2W6MWN8zXPayvGinx+PYRne9h8WiyJN9N44aG4No0kd4mXPO9vGXAg
8dhNZxKMXmWOqOBcme6aIVGJQtSEEjTl3qqSxYj8kUdIiR4Fznf5cYvjbzSgXRSi
tJdQu5eOk28c99t4TtnLzR1B6qrPDtwjtApoxw5YsjZKbKweOm+DqzhRVSOsoQE5
DC6CFkmdWybz+2O/UNA4qcJIq4bAHYfYskFHkmkIix71YLIthWq6F9+Fpnq8ZQp5
kX+TqxDyAqhirYhl3kJ/DSstpPe+GjebFWPNkvfXxJ8iwnOUqOzuVerpbWFYF8SC
B0lpxMncoJgx5dIM0QRFcw17rv1+GK8Ga0+8avhZ5hqd4raUvxlY7ZInwsMn70sN
Jc2hH70fYF9U3WW4o6p2IY/bh8V0Pu9nMJIILXFuSN7PdcNpSGk3tdQgJ32seAbc
OWfnABEBAAGJAiUEGAECAA8FAmLNircCGwwFCQPCZwAACgkQNQEd08vC4KtZvBAA
kyJd2aNJhpyQQMVZHUdnXwl/W16r+HwO+gg1nXBTj0swNiNKq9mk78IWKJW+XIEC
5RucAq4c2pg8lCHOwuIpPexEKsHTe6PjFnx6DT6ykaZjZQNiPJAl7QoPu0eUGW2L
vBG4/qlJNKzQQQUHBLMV8MlQhNdx5wBbs8s6UGQ0Q+YUzYCBZ4thQb8SfRSNDGc3
0DitLJD+hSJGeDQ38/1brF8hCQuJcOMYpKv7rWDpBDXY0oWhDWCkQo0F4+Ke+8ou
IUMWc/toyhIHcjRP6XpihC2utFfQE4hlugRn2lOI8vkCQkEidXqYZzvfA7zqdmjX
LYWkISsF6jd7tD/ScN8h9KW58Rq/fTiQ5eXsWbV5fY0wMsJJ6uXL/8/yfvJxw/Zp
YkHA+gIMvdmxTxP3qd+W9Hq+vToD8MbGqPFrVb29+xF6VmzB2KFyvNbiGnwSR7Ke
FuFbKkIoly1hlc7s/N1maU2LS4ByvPh0Q6h7AJO7jJL+/wu2kDoQbCLZ85nRGAth
j2b1ZsftaZk4vdZQrRoTovta5gVYJjxMYwFlBqoucXZF3VXoiBz0Hec6Oh9YsK3a
GGO1yxMkDDJPUSl5p43dfJIg9nVvpB37tFp+vn7Ogu01SLYsXChQWdNdw3BQT4pl
Plb3Yd+plt7shbg9LTSafrv7nNukxPzZmVk1FL9w3Ec=
=m5/V
-----END PGP PUBLIC KEY BLOCK-----
```
### Deposit To Card Transfer
#### Introduction
Deposit to card transfer (D2C) is a money transfer from Connecting Party bank account (Deposit) to Receiver bank card number (PAN) or tokenized card data (Card Reference ID). Deposit to card transfer is made in three steps:
Initial payment – any transaction type with present cardholder data will work as initial payment - sale, preauth, transfer, etc. It is important to make the initial payment the most secure way in order to guarantee that a real card holder is registering the card.
Card registration – get card-ref-id (Card Reference ID) and register Customer’s card in their profile. Card Reference ID can be used unlimited number of times, while the bank card is active.
Money transfer – run v4/transfer-by-ref/ API command using destination-card-ref-id obtained on previous step.
See terms definitions in [Glossary](https://doc.payneteasy.com/integration/reference/glossary.html.md).
#### Deposit To Card Transfer Flow
```plantuml
@startuml
skinparam roundcorner 20
skinparam sequenceArrowThickness 1
skinparam maxmessagesize 1200
skinparam sequenceParticipant underline
actor Payer as P
participant "Connecting Party" as A
participant "Payneteasy" as B
autonumber
hnote over P,B : Initial payment
==Card registration==
A -> B: api/v2/create-card-ref
activate A
activate B
B --> A: Return card-ref-id
deactivate B
A -> A: Assign Card Reference ID to Customer's profile
deactivate A
==Get card info==
group optional
A -> B: api/v2/get-card-info/
activate A
activate B
B -> A: Return Card info
deactivate A
deactivate B
end
==Deposit To Card==
A -> B: api/v4/transfer-by-ref/
activate A
activate B
B --> A: Response with Order ID
B -> B: Process\nDeposit
group Get Final Status
== Receive Connecting Party Callback ==
A <- B: Callback with Final Status
A --> B: HTTP 200
deactivate B
== Order Status Request ==
A -> B: Get Status by Order ID
activate B
B --> A: Final Status
deactivate A
deactivate B
end
@enduml
```
(1) To implement Card registration and get Card Reference ID see [/api/v2/create-card-ref](https://doc.payneteasy.com/integration/API_commands/api_v2_create-card-ref.html.md).
(3) Connecting Party assigns Card Reference ID to Customer’s profile, after which Connecting Party shows the page saying that the card registration is successful and initial payment approved.
(4) To implement Card information request by Card Reference ID see [/api/v2/get-card-info](https://doc.payneteasy.com/integration/API_commands/api_v2_get-card-info.html.md). The contents of response to this request can be used to show information about previously used card to Payer or to update Connecting Party database. This request can be made anytime if Connecting Party has Card Reference ID.
(6) Connecting Party initiates deposit to card transfer (D2C). To implement deposit to card request see [/api/v4/transfer-by-ref](https://doc.payneteasy.com/integration/API_commands/api_v4_deposit_transfer.html.md)
(9) To implement callback with final status handling see [Connecting Party Callback](https://doc.payneteasy.com/integration/API_commands/merchant_callback_parameters.html.md).
(11) To implement order status request see [/api/v2/status/](https://doc.payneteasy.com/integration/API_commands/api_v2_status.html.md). Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.
(12) Final Status can be sent by Connecting Party based on internal business model or by Receiver’s request.
### Direct Bank transfer
#### Introduction
A Direct Bank transfer is an international bank transfer made via the Swift network. This method allows to process bank transfers using the Direct method (with direct transfer of the Payer’s bank data).
See terms definitions in [Glossary](https://doc.payneteasy.com/integration/reference/glossary.html.md).
#### Direct Bank Transfer Flow
```plantuml
skinparam roundcorner 20
skinparam sequenceArrowThickness 1
skinparam maxmessagesize 1200
skinparam sequenceParticipant underline
actor Payer
participant "Connecting Party" as A
participant "Payneteasy" as B
autonumber
Payer -> A: Checkout
activate A
A -> B: /api/v2/bank-wire-transfer/
activate B
B --> A: Order ID
B -> B: Process\nBank Wire Transfer
group Get Final Status
== Receive Connecting Party Callback ==
A <- B: Callback with Final Status
A --> B: HTTP 200
deactivate B
== Order Status Request ==
A -> B: Get Status by Order ID
activate B
B --> A: Final Status
deactivate B
end
A --> Payer: Show result
deactivate Payer
deactivate A
```
(2) To implement bank wire transfer request see [/api/v2/bank-wire-transfer/](https://doc.payneteasy.com/integration/API_commands/api_v2_bank-wire-transfer.html.md).
(5) To implement callback with final status handling see [Connecting Party Callback](https://doc.payneteasy.com/integration/API_commands/merchant_callback_parameters.html.md).
(7) To implement order status request see [/api/v2/status/](https://doc.payneteasy.com/integration/API_commands/api_v2_status.html.md). Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.
### e Check Sale
#### Introduction
Payneteasy allows Connecting Party to accept electronic check payments for goods and services purchased via e-commerce websites. An electronic check works much like a regular check, only instead of using a paper check to provide their bank account, routing number and payment authorization, the Payer provides Connecting Party with the necessary payment information through other methods, allowing the Connecting Party to process the information electronically.
See terms definitions in [Glossary](https://doc.payneteasy.com/integration/reference/glossary.html.md).
#### e Check Flow
```plantuml
skinparam roundcorner 20
skinparam sequenceArrowThickness 1
skinparam maxmessagesize 1200
skinparam sequenceParticipant underline
actor Payer
participant "Connecting Party" as A
participant "Payneteasy" as B
autonumber
Payer -> A: Checkout
activate A
A -> B: /api/v2/sale-echeck/
activate B
B --> A: Order ID
B -> B: Process\nSale-eCheck
group Get Final Status
== Receive Connecting Party Callback ==
A <- B: Callback with Final Status
A --> B: HTTP 200
deactivate B
== Order Status Request ==
A -> B: Get Status by Order ID
activate B
B --> A: Final Status
deactivate B
end
A --> Payer: Show result
deactivate Payer
deactivate A
```
(2) To implement sale-e Check request see [/api/v2/sale-echeck/](https://doc.payneteasy.com/integration/API_commands/api_v2_sale-echeck.html.md).
(5) To implement callback with final status handling see [Connecting Party Callback](https://doc.payneteasy.com/integration/API_commands/merchant_callback_parameters.html.md).
(7) To implement order status request see [/api/v2/status/](https://doc.payneteasy.com/integration/API_commands/api_v2_status.html.md). Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.
### FAQ
#### Gather useful information
Please gather this information and provide it to support to quickly resolve issues which happened during the integration
> - Please indicate whether sandbox or production environments were used.
> - Please indicate whether or not the functionality worked at one time or not. If so, please indicate since when it stopped working.
> - Please add relevant log information ( orderid, serial-number, client_orderid, ENDPOINTID, ENDPOINTGROUPID) when any is available.
#### Frequently asked questions during the integration
##### What does INVALID_CONTROL_CODE error mean?
The calculation of the signature may be different for different types of API calls. The most common reasons are:
> - Wrong credentials. Check credentials received from Payment Gateway manager.
> - API calls to sandbox had production environment URL or vise versa.
> - Production credentials (ENDPOINTID, ENDPOINTGROUPID, control key, etc) were used on sandbox or vise versa.
> - Parameters for signature calculation are in incorrect order.
> - The amount of the transaction is not converted to minimal decimal units.
The best way to check signature calculation is to use the request builder sections in API documentation:
> - Choose the correct URL from the combobox with API calls selection, if present.
> - After pressing the Sign button, please check signature value for the String to sign whether the same string is being signed or not.
> - If the signing string looks correct, signature value must be the same as in Signature field.
> - Login to UI and find the particular API requests and responses on the Integration panel screen in Tools section.
##### What is the difference between ENDPOINTID or ENDPOINTGROUPID?
Payneteasy gateway can support any currency.
> - ENDPOINTID supports only one currency.
> - ENDPOINTGROUPID can support as many currencies as needed. Full list of currencies should be sent to Payment Gateway manager for project configuration.
Due to the different nature of these two entities it is impossible to use ENDPOINTID instead of ENDPOINTGROUPID and vise versa.
##### Is it possible to use Synchronous API?
All APIs are asynchronous, see [Async-Response](https://doc.payneteasy.com/integration/general_api_usage/async_response.html.md). If using synchronous API is required, it should be implemented on Connecting Party side. Ask Payment Gateway manager to refine if it is possible to make synchronous calls in your integration.
##### How to implement 3-D Secure (Verified by Visa / Master Card Secure Code) on Native mobile app?
Even in native app embedded Web View component should be used in order to open banking ACS server URL.
To process the transactions without redirect to 3-D Secure page Connecting Party’s application must meet the following requirements:
> - Payers are identified and there is a low fraud probability, it this case Connecting Party can ask Payment Gateway manager to open non3D account.
> - Connecting Party have PCI DSS certificate and can gather cardholder data on their side, in this case Connecting Party can ask Payment Gateway manager to open account with Direct API support to avoid unnecessary redirects.
##### What is client_orderid?
This transaction identifier is generated on Connecting Party side. It is also referred as merchant-order-id in some APIs.
##### How to get an approved transaction on sandbox environment?
For different types of API Payneteasy have different mechanisms for getting approved transactions and transactions in other statuses. For e-commerce transactions Payneteasy is using different CVVs, see [test_cards](https://doc.payneteasy.com/integration/general_api_usage/test_scenarios.html.md). For mPOS transactions see [mpos](https://doc.payneteasy.com/integration/mpos_api_index.html.md).
##### Why response is formatted with (0xA)?
To improve readability of the response in most APIs, Payneteasy adds (0xA) character at the end of each parameters value. To process the response from the Payment Gateway please, implement the handling mechanism for this character.
##### Is it possible to use redirect_url to get transaction status for backoffice?
It is not advisable.
All parameters for the final redirect are passed through the customer’s browser. Parameters can be lost during the transmission over the internet. To get guaranteed result from Payneteasy gateway see [Connecting Party Callbacks](https://doc.payneteasy.com/integration/API_commands/merchant_callback_parameters.html.md).
##### Is it possible to use GET instead of POST to submit data to Payneteasy gateway?
Unfortunately it is not possible.
Transmitting parameters using HTTP GET is strictly forbidden to avoid possible data leaks.
##### What does INVALID_CALLBACK_URL mean?
Please use full public URL with http:// or https://
For example, please pass [http://www.example.com](http://www.example.com) or [https://www.example.com](https://www.example.com) instead of www.example.com. Only following ports are allowed:
> - 80, 8080 for HTTP
> - 443, 8443 for HTTPS
##### How often can transaction status be polled?
Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.
Normally it takes up to 5 seconds to process the non3D transaction and up to 60 minutes for 3D transaction. Transactions made via some payment methods or payment channels, especially processed in offline mode, might stay in non-final status for several hours or even days, so there is no point in polling transaction status often for such cases. Connecting Party should rely on callback to get transaction final status, see [Connecting Party Callbacks](https://doc.payneteasy.com/integration/API_commands/merchant_callback_parameters.html.md).
##### Why transaction has been declined with base 64 fail reason?
Please use urldecode to process html parameter in Payneteasy gateway response.
Payneteasy is trying to help Connecting Party to correctly handle API responses. Base64 test gives Connecting Party an ability to check if 3DS page provided by bank will be correctly handled on production environment. If Connecting Party is getting this error, this means that urldecode probably was not used to parse the Payneteasy gateway response or probably it works in incorrect way (for example in some versions of PHP it is needed to use rawurldecode instead).
### Final Redirect
#### Final Redirect Parameters
Final redirect to merchant (represented by Connecting Party) website is performed when Payer ends payment flow. Final redirect is initiated from within Payer’s browser using HTTP POST method.
| Redirect parameter name | Description |
|---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| status | See [Status List](https://doc.payneteasy.com/integration/reference/statuses.html.md) for details. |
| orderid | Order id assigned to the order by gate.payneteasy.eu. |
| merchant_order | Connecting Party order id. |
| client_orderid | Connecting Party order id. |
| error_message | If status is declined or error this parameter contains the reason for decline or error details. |
| control | Checksum used to ensure that it is gate.payneteasy.eu (and not a fraudster) that initiates the request. This is SHA-1 checksum of the concatenation status + orderid + client_orderid + merchant-control. |
| descriptor | Gate descriptor. |
| processor-tx-id | Acquirer transaction identifier. |
| amount | Actual transaction amount. |
| bin | Bank BIN of customer credit card number. |
| type | The type of response. |
| card-type | Type of customer credit card. |
| phone | Customer phone. |
| last-four-digits | Last four digits of customer credit card number. |
| card-holder-name | Cardholder name. |
| error_code | Error Code. |
Connecting Party should not use Payer redirect as a main source of information about transaction’s final status. If Connecting Party has passed server_callback_url in initial transaction request, Payment Gateway will call this URL. Connecting Party may use it for custom processing of the transaction completion, e.g. to collect sales data in Connecting Party database. The parameters sent to this URL are specified in [Connecting Party Callbacks](https://doc.payneteasy.com/integration/merchant_callback_parameters.html.md).
#### Final Redirect Request Example
Payment Gateway sends POST redirect to https://connectingparty.com/pay/redirect?token=some_token with params in x-www-form-urlencoded format:
```http
error_message=null
&processor-tx-id=PNTEST-1788082
&amount=100.00
&merchant_order=test
&orderid=1788082
&client_orderid=test
&bin=444455
&control=854f38715ee6bf43fa18e3ca202985a06e0ae755
&gate-partial-reversal=enabled
&descriptor=DEMO1
&gate-partial-capture=enabled
&type=sale
&card-type=VISA
&phone=%2B31201112233
&last-four-digits=1111
&card-holder-name=TEST+HOLDER
&status=approved
```
### Fiscalization service
#### Overview
Fiscalization service is used for registration of financial cheques and invoices in Payneteasy payment gateway and their further processing. Fiscalization is supported for both initial and recurring Sale and Preauth transactions, via Server-To-Server or Form integration. See the suitable integration scenario in respective Use-Cases or ask support manager for details. Transaction with cheque/invoice is processed by Payneteasy Payment Gateway with additional requests for tax accounting.
#### Fiscalization service parameter (cheque)
In order to initiate a transaction with the use of fiscalization service, Connecting Party sends an HTTPS POST request for sale or preauth transaction with additional parameter.
| Request Parameters | Type | Comment |
|----------------------|-------------|-----------------------------------------------------------------------------------|
| cheque | Json string | Financial cheque or invoice. Mandatory for transaction request with Fiscalization |
#### Json string structure for cheque parameter
A simple json string example for cheque parameter:
```http
{
"cheque_type" : 1,
"tax_system" : 1,
"positions" : [
{
"quantity" : 2,
"price" : 322.94,
"tax" : 4,
"description" : "Product/Service 1"
},
{
"quantity" : 1,
"price" : 500,
"tax" : 4,
"description" : "Product/Service 2"
}
]
}
```
Json string parameters:
| Parameter | Type | Comment | Possible values |
|-------------|-------------|--------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| cheque_type | Decimal | Calculation type/sign | 0 - income, 1 - expense, 2 - return of income, 3 - return of expense |
| tax_system | Decimal | Tax system | 0 - General taxation system, 1 - Simplified income taxation system, 2 - Simplified income minus expense taxation system, 3 - Unified tax on imputed income, 4 - Unified agricultural tax, 5 - Patent system of taxation |
| positions | Array | Array of products/services | Array of products/services |
| quantity | Decimal | Quantity of product/service | |
| price | Decimal | Price per product/service considering discounts and mark-ups | |
| tax | Decimal | value-added tax | 1 - 22% value-added tax, 2 - 10% value-added tax, 3 - 0% value-added tax, 4 - without value-added tax, 5 - 22/122 value-added tax, 6 - 10/110 value-added tax |
| description | String(128) | Description of product/service | |
> **Note:** Please take into consideration that the total price of all products/services which are provided in positions array should be equal to amount parameter value of sale request.
#### Example of transaction request with fiscalization
This example of Server-To-Server Sale request body with fiscalization displays how to correctly include the cheque parameter. Response example is provided in relevant API command documentation.
```http
client_orderid=902B4FF5
&order_desc=Test Order Description
&first_name=John
&last_name=Smith
&ssn=1267
&birthday=19820115
&address1=100 Main st
&city=Seattle
&state=WA
&zip_code=98102
&country=US
&phone=%2B12063582043
&cell_phone=%2B19023384543
&amount=700.00
&email=john.smith@gmail.com
¤cy=USD
&ipaddress=65.153.12.232
&site_url=www.google.com
&credit_card_number=4538977399606732
&card_printed_name=CARD HOLDER
&expire_month=12
&expire_year=2099
&cvv2=123
&purpose=user_account1
&redirect_url=https://doc.payneteasy.com/doc/dummy.htm
&server_callback_url=https://httpstat.us/200
&merchant_data=VIP customer
&cheque={ "cheque_type" : 1, "tax_system" : 1, "positions" : [ { "quantity" : 2, "price" : 100.00, "tax" : 4, "description" : "Product/Service 1" }, { "quantity" : 1, "price" : 500, "tax" : 4, "description" : "Product/Service 2" } ] }
&control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483
```
### Forms Customization
#### Payment Page Display Logic
```plantuml
skinparam ConditionEndStyle hline
: (1) Initiate transaction;
if ((2) Additional Payer input required?) then (yes)
: (3) return input form;
: (4) submit form;
else (no)
endif
if ((5) External form required?) then (yes)
: (6) request external form from the payment provider;
: (7) redirect to external form;
: (8) submit form on payment provider side;
else (no)
endif
: (9) show wait form;
: (10) process transaction;
: (11) show finish form or redirect \nto Connecting Party website;
```
(1) Transactions can be initiated with API requests, batch upload or via Virtual terminal on UI. Each payment method has its own payment page display logic.
> **Note:** Payment Cashier might have multiple transactions initiated within the same payment session, because it can have multiple payment methods available for the Payer. When Payer selects payment tab, respective auxiliary transaction is initiated. See [Payment Cashier Page Customization](#payment-cashier-page-customization-reference).
(3) For credit card payment method form is displayed on Payment Gateway side and can be customized. See [Payment Page Customization](#payment-page-customization-reference). Some other payment methods may have additional forms on Payment Gateway side. Contact Payneteasy support for details.
(7) Some payment methods require the Payer to be redirected to their own form. That form is not hosted by Payment Gateway and can\`t be customized.
(9) Until transaction reaches final status, Payment Gateway displays [Wait Form](#wait-page-customization-reference) for the Payer.
(11) After the transaction reaches the final status, Payment Gateway displays [Finish Form](#finish-page-customization-reference) for the Payer or [Redirect](https://doc.payneteasy.com/integration/API_commands/final_redirect.html.md) to Connecting Party website.
#### Payment Page Customization
##### Payment Page Example
```html
Order #$!MERCHANT_ORDER_ID - $!ORDERDESCRIPTION
Total amount: $!AMOUNT $!CURRENCY to $!MERCHANT
```
> **Note:** The code described below allows to submit destination card data in [Transfer](https://doc.payneteasy.com/integration/api_use_cases/transfer_form.html.md) type transactions:
```html
```
##### Payment Page Autofill
If Connecting Party wants to use autofill in payment form, certain element attributes