MENU navbar-image

Introduction

PayPipes simplifies payment management by consolidating various payment methods and gateways into a single, easy-to-use API. You can integrate with PayPipes using our WooCommerce plugin or direct server-to-server (S2S) integration.

Our system includes a merchant back office where you can view all your transactions in one place. We also offer customizable payment pages for redirecting users, ensuring all card payments are PCI DSS compliant.


Features

Payment Pages

PayPipes provides redirect integration, offering different types of payment pages for customers. We have our own wire payment page and card payment page, where you can customize the logo and brand colors. Users enter their card details in a unified form, and we handle routing and cascading to selected gateways on the backend. The user always sees the same payment page for each payment type. For other payment types beyond card and wire, we may redirect the user to the gateway's payment page.

Routing

We offer routing for card payment gateways based on currency, card brand, and transaction volume. You can choose where to route each card payment, optimizing success rates, fees, or other preferences. You can also set volume proportions for each card gateway with the same brands and currencies. For example, if you have two card gateways processing EUR and VISA, you can set an 80/20 volume proportion. If no initial setting is provided, we automatically select available gateways based on currency and card brand, keeping the proportions even.

Cascading

Cascading is a card payment feature on our payment pages that improves success rates by trying the next available gateway if the initial transaction is declined. We keep the user on our payment page and prompt them to try the payment again with a different gateway on the backend. This maximizes the success of each payment. If you prefer not to cascade transactions, you can disable this feature or send a request to a specific gateway.

Retry

In cases of decline due to insufficient funds or reaching card limits, we inform the user on our payment page to add funds or raise limits and try the same gateway again, increasing the chance of success. If the payment fails a second time, cascading to the next available gateway occurs.

Back Office

Our back office allows you to view all transactions processed by PayPipes in one place. You can also trigger refund or reverse endpoints, check user, payment, or card info in payment details, manage back office operators, and export data to CSV.

Delayed Payments

To prevent mistakes in refunding or reversing payments, we allow you to set a delay before the actual request is sent to the payment gateway, enabling you to cancel it if necessary.


How to Start

To get started, contact us at info@paypipes.com. We will provide all the information you need for seamless integration, tailoring our approach to your specific needs.

We will register you and provide access to the back office and API credentials, so you can begin your integration. We offer flexible communication and support.


Environments

We offer both staging and production environments for our API and back office, allowing you to test everything before starting to receive payments.

API Endpoints:

Back Office:

Resources

Authentication

We use OAuth 2.0 for authentication. To obtain an access token, send a POST request over HTTPS to the /oauth/token endpoint. Upon a successful request, you will receive an access token, valid for 72 hours. It is recommended to request a new token before each transaction to ensure validity.

All requests must be authenticated using your API credentials. Authentication data should be sent as POST parameters to verify against a specific entity.

Example request:
curl --request POST \
    "https://secure.staging.paypipes.net/oauth/token" \
    --header "Content-Type: application/json (or application/x-www-form-url-encoded)" \
    --data "{
    \"client_id\": \"PUT_YOUR_CLIENT_ID_HERE\",
    \"client_secret\": \"PUT_YOUR_CLIENT_SECRET_HERE\",
    \"grant_type\": \"client_credentials\"
}"
const url = new URL(
    "https://secure.staging.paypipes.net/oauth/token"
);

const headers = {
    "Content-Type": "application/json (or application/x-www-form-url-encoded)",
    "Accept": "application/json",
};

let body = {
    "client_id": "PUT_YOUR_CLIENT_ID_HERE",
    "client_secret": "PUT_YOUR_CLIENT_SECRET_HERE",
    "grant_type": "client_credentials"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://secure.staging.paypipes.net/oauth/token';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Content-Type' => 'application/json (or application/x-www-form-url-encoded)',
        ],
        'json' => [
            'client_id' => 'PUT_YOUR_CLIENT_ID_HERE',
            'client_secret' => 'PUT_YOUR_CLIENT_SECRET_HERE',
            'grant_type' => 'client_credentials',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://secure.staging.paypipes.net/oauth/token'
payload = {
    "client_id": "PUT_YOUR_CLIENT_ID_HERE",
    "client_secret": "PUT_YOUR_CLIENT_SECRET_HERE",
    "grant_type": "client_credentials"
}
headers = {
  'Content-Type': 'application/json (or application/x-www-form-url-encoded)'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (200, Successful response):


{
    "token_type": "Bearer",
    "expires_in": 259200,
    "access_token": "eyJ0eXAiOiJKL1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiI5N2VhNjdiYS03ZWNkLTRkODYtYjRlNC1hYjI2YzY2NGMyNTYiLC JqdGkiOiJjMTM1NjU5OWRlNjE0Y2ViNWU3ZDJkNmI5MTE3MTcxMWE2ZjY5OTlkMDM4MjIyNmY2ZmIwOGI4MWJiOGM1MjgxNGY4ODQxZWJlMjZkZmRmNyI sImlhdCI6MTcxNzc1NjUzOC45MTIwNjEsIm5iZiI6MTcxNzc1NjUzOC45MTIwNjIsImV4cCI6MTcxODAxNTczOC45MTAxNDgsInN1YiI6IiIsInNjb3Blc yI6W119.BctTyyN20SkMH200hJaP3NGqQ69Xu7RT2aAmymprq2TRDBH02F3jUlzkufSkR3Zp6pW1_1c7ridFoqjjHCJKrpxQND9TzcrGE9QjUDiFpswzbE 9ljDQ1HRUYfIvFCqGVS8PQ69J3-i-FPl4uwcTNJ1mq3eoI0A-X5d2J0INPRou-HgbQYYv3vTtm_OCVriuSHm8QCMVdej5Xq41bDzuxIsgh_OPgARUBs51y q8JjPtBAS5z_OArus1YSCfx0gyYbvy2VJuOGgPILCzUpboseaWNO2OHdIjUD1h8foMXhDlCScn0wfJFwOsEUl6Nn22DZIzToCTOwibd-lwzmir4-OAJCs ManyyfRdkU2aqb5OnVFjauzIMnznswGq9d3IzkV6cimWsDs7ZwD6RwGv5I0yF6NGsTfCah_DO9Ch9z-iNVjJe27aO0EhgdpHELIkmnTprfVYPcD2LTKJ5 6ap8g5JTmtsykFKY1sK8WoAK12YqjZRdfRkiiqltJc1x2569hGFT102VCnH5ECpDmh2EAyOLx0d_E7juS_dxgQrVIZAOzcTyLZN6ckM03PBp4n3bhLCoi U1kptvFQ2vgpxavt6xF7ESPAmgEUj0zo0mIxnVqRegPJm1hRxlIplb1nfR-mDpG3FSn8Ms_RxtAksghFmLXysqLpipiRbiF540v8DXTz"
}
 

Example response (401, Error response):


{
    "error": "invalid_request",
    "error_description": "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.",
    "hint": "Check the `client_id` parameter",
    "message": "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed."
}
 

Request      

POST oauth/token

Headers

Content-Type      

Example: application/json (or application/x-www-form-url-encoded)

Body Parameters

client_id   string   

Merchant's client_id related to terminal. Example: PUT_YOUR_CLIENT_ID_HERE

client_secret   string   

Merchant's client_secret related to terminal. Example: PUT_YOUR_CLIENT_SECRET_HERE

grant_type   string   

Merchant's API access type - "client_credentials". Example: client_credentials

Response

Response Fields

Response 200      

Successful response

token_type   string   

Specifies the type of token that is being returned. In this case, it is a "Bearer" token. Example: Bearer

expires_in   int   

Indicates the number of seconds until the token expires. This value is used to determine the token's lifetime. Example: 259200

access_token   string   

The actual token string that is used to authenticate API requests. Example: eyJ0eXAiOiJKL1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiI5N2VhNjdiYS03ZWNkLTRkODYtYjRlNC1hYjI

Response 401      

Error response

error   string   

A short code or identifier for the error that occurred. Example: invalid_request

error_description   string   

A more detailed description of the error, providing context about what went wrong with the request. Example: The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.

hint   string   

An additional piece of information to help diagnose or resolve the error. Example: Check theclient_idparameter

message   string   

A user-friendly message that can be displayed or logged. It is often similar or identical to the error_description. Example: The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.

Transaction

Purchase

requires authentication

The purchase endpoint creates a transaction using the customer token by sending a POST request over HTTPS to the /purchase endpoint. This triggers the creation of a new transaction

Example request:
curl --request POST \
    "https://secure.staging.paypipes.net/api/v2/purchase" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json (or application/x-www-form-url-encoded)" \
    --data "{
    \"order_id\": \"ORD1234567890\",
    \"amount\": \"100.00\",
    \"currency\": \"USD\",
    \"description\": \"Payment for order ORD1234567890\",
    \"return_url\": \"https:\\/\\/example.com\\/result\",
    \"callback_url\": \"https:\\/\\/example.com\\/callback\",
    \"cancel_url\": \"https:\\/\\/example.com\\/cancel\",
    \"origin\": \"web\",
    \"customer_token\": \"11cc649a-cdab-4b26-b9ec-781920174ca6\",
    \"card_token\": \"E75C608271E3852BA81A87540085\",
    \"gateway\": \"unlimit\",
    \"type\": \"card\",
    \"language\": \"en\",
    \"simulator\": true,
    \"save_card_for_future_use\": true,
    \"billing_address\": true
}"
const url = new URL(
    "https://secure.staging.paypipes.net/api/v2/purchase"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json (or application/x-www-form-url-encoded)",
    "Accept": "application/json",
};

let body = {
    "order_id": "ORD1234567890",
    "amount": "100.00",
    "currency": "USD",
    "description": "Payment for order ORD1234567890",
    "return_url": "https:\/\/example.com\/result",
    "callback_url": "https:\/\/example.com\/callback",
    "cancel_url": "https:\/\/example.com\/cancel",
    "origin": "web",
    "customer_token": "11cc649a-cdab-4b26-b9ec-781920174ca6",
    "card_token": "E75C608271E3852BA81A87540085",
    "gateway": "unlimit",
    "type": "card",
    "language": "en",
    "simulator": true,
    "save_card_for_future_use": true,
    "billing_address": true
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://secure.staging.paypipes.net/api/v2/purchase';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json (or application/x-www-form-url-encoded)',
        ],
        'json' => [
            'order_id' => 'ORD1234567890',
            'amount' => '100.00',
            'currency' => 'USD',
            'description' => 'Payment for order ORD1234567890',
            'return_url' => 'https://example.com/result',
            'callback_url' => 'https://example.com/callback',
            'cancel_url' => 'https://example.com/cancel',
            'origin' => 'web',
            'customer_token' => '11cc649a-cdab-4b26-b9ec-781920174ca6',
            'card_token' => 'E75C608271E3852BA81A87540085',
            'gateway' => 'unlimit',
            'type' => 'card',
            'language' => 'en',
            'simulator' => true,
            'save_card_for_future_use' => true,
            'billing_address' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://secure.staging.paypipes.net/api/v2/purchase'
payload = {
    "order_id": "ORD1234567890",
    "amount": "100.00",
    "currency": "USD",
    "description": "Payment for order ORD1234567890",
    "return_url": "https:\/\/example.com\/result",
    "callback_url": "https:\/\/example.com\/callback",
    "cancel_url": "https:\/\/example.com\/cancel",
    "origin": "web",
    "customer_token": "11cc649a-cdab-4b26-b9ec-781920174ca6",
    "card_token": "E75C608271E3852BA81A87540085",
    "gateway": "unlimit",
    "type": "card",
    "language": "en",
    "simulator": true,
    "save_card_for_future_use": true,
    "billing_address": true
}
headers = {
  'Authorization': 'Bearer {ACCESS_TOKEN}',
  'Content-Type': 'application/json (or application/x-www-form-url-encoded)'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (200, Successful response):


{
    "redirect_url": "https://secure.paypipes.com/v2/redirect/f10f8c7b-a18b-46a2-978a-dadb5ce80987",
    "expires_at": "2024-05-03 14:14:34",
    "purchase_request_id": "79e03b19c411f001981ca4a6d30aa407300c23b1"
}
 

Example response (400, Error response):


{
    "error": "Bad request",
    "code": 200000
}
 

Example response (401, Error response):


{
    "error": "Unauthenticated",
    "code": 100001
}
 

Example response (403, Error response):


{
    "error": "Unauthorized",
    "code": 100004
}
 

Example response (404, Error response):


{
    "error": "Record not found",
    "code": 200007
}
 

Example response (405, Error response):


{
    "error": "The specified method for the request is invalid",
    "code": 200008
}
 

Example response (410, Error response):


{
    "error": "Transaction has expired (Transaction ID: #ID)",
    "code": 200037
}
 

Example response (422, Error response):


{
    "error": "Invalid currency",
    "code": 100003
}
 

Request      

POST api/v2/purchase

Headers

Authorization      

Example: Bearer {ACCESS_TOKEN}

Content-Type      

Example: application/json (or application/x-www-form-url-encoded)

Body Parameters

order_id   string   

Merchant's internal unique ID for the transaction. Must be at least 1 character. Must not be greater than 40 characters. Example: ORD1234567890

amount   string   

The value representing the actual amount for the transaction. The decimal points must match the currency's decimal point length. For example, for USD currency, valid amounts include "5.99", "6.00", or "6". An amount like "5.995" would throw a validation error due to an invalid amount specified. Must not be greater than 10 characters. Example: 100.00

currency   string   

The currency code for the transaction, which must comply with the ISO 4217 standard and be represented by a three-letter code. The cy_code of an existing record in the currencies table. Example: USD

description   string   

A description of the transaction. Must not be greater than 255 characters. Must be at least 5 characters. Example: Payment for order ORD1234567890

return_url   string   

The URL to which the user is redirected upon the completion of the transaction. Must be a valid URL. Must not be greater than 2048 characters. Example: https://example.com/result

callback_url   string  optional  

URL used to receive callback/webhook notification with information about the transaction. Must be a valid URL. Must not be greater than 2048 characters. Example: https://example.com/callback

cancel_url   string  optional  

The URL to which the user is redirected if the transaction is canceled. Must be a valid URL. Must not be greater than 2048 characters. Example: https://example.com/cancel

origin   string  optional  

Indicates the source from which the request originates. Example: web

Must be one of:
  • web
  • ios
  • android
customer_token   string  optional  

A token identifying the customer. This field is required when card_token is not present. Example: 11cc649a-cdab-4b26-b9ec-781920174ca6

card_token   string  optional  

A token identifying the card of the customer used for the transaction. This field is required when customer_token is not present. Example: E75C608271E3852BA81A87540085

gateway   string  optional  

The payment gateway used to process the transaction. Available gateways can be found here: Gateways. Example: unlimit

type   string  optional  

Refers to type of the gateway. Gateways and their types can be found here: Gateways.

Must be one of:

  • card
  • wire
Example: `card`
language   string  optional  

The language code for the transaction, which must adhere to the ISO 639-1 standard and be represented by a two-letter code. Example: en

simulator   boolean  optional  

Enable the simulator for the transaction. Accepted inputs are true, false, 1, 0, "1", and "0". Example: true

save_card_for_future_use   boolean  optional  

This parameter determines whether the user’s card details should be securely stored for future transactions. Accepted inputs are true, false, 1, 0, "1", and "0". Example: true

billing_address   boolean  optional  

This parameter specifies whether the merchant wishes to display the customer billing address section on the payment page. Accepted inputs are true, false, 1, 0, "1", and "0". Example: true

Response

Response Fields

Response 200      

Successful response

redirect_url   string   

This parameter provides the URL to which the client should be redirected. Example: https://secure.paypipes.com/v2/redirect/f10f8c7b-a18b-46a2-978a-dadb5ce80987

expires_at   string   

Expiration date and time of the redirect URL. Example: 2024-05-03 14:14:34

purchase_request_id   string   

Unique ID of the purchase. Example: 79e03b19c411f001981ca4a6d30aa407300c23b1

Response 400|401|403|404|405|410|422      

Error response

error   string   

This parameter contains a message describing the error that occurred. Example: Invalid currency

code   integer   

This parameter provides a numeric code that uniquely identifies the specific error. Example: 100003

Card process

requires authentication

The card process endpoint is used for direct server-to-server card transaction processing using raw card details by sending a POST request over HTTPS to the /card/process endpoint.

Example request:
curl --request POST \
    "https://secure.staging.paypipes.net/api/v2/card/process" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json (or application/x-www-form-url-encoded)" \
    --data "{
    \"jwe\": \"eyJhbGciOiJ...\"
}"
const url = new URL(
    "https://secure.staging.paypipes.net/api/v2/card/process"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json (or application/x-www-form-url-encoded)",
    "Accept": "application/json",
};

let body = {
    "jwe": "eyJhbGciOiJ..."
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://secure.staging.paypipes.net/api/v2/card/process';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json (or application/x-www-form-url-encoded)',
        ],
        'json' => [
            'jwe' => 'eyJhbGciOiJ...',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://secure.staging.paypipes.net/api/v2/card/process'
payload = {
    "jwe": "eyJhbGciOiJ..."
}
headers = {
  'Authorization': 'Bearer {ACCESS_TOKEN}',
  'Content-Type': 'application/json (or application/x-www-form-url-encoded)'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (200, Successful response):


{
    "version": 2,
    "orderID": "ORD1234567890",
    "trxID": "6c37e2d5-92cc-4241-a9f8-9813720aec64",
    "trxType": "Purchase",
    "amount": "15.00",
    "currency": "EUR",
    "status": "Waiting",
    "paymentStatus": null,
    "statusCode": "200",
    "statusDescription": "",
    "declineCode": null,
    "created": "2024-06-04T10:50:38.000000Z",
    "cardToken": "E75C608271E3852BA81A87540085",
    "customerToken": "11cc649a-cdab-4b26-b9ec-781920174ca6",
    "description": "Charge transaction with ID #ORD1234567890",
    "gateway": "ecommpay",
    "applePay": false,
    "googlePay": false,
    "refNo": null,
    "requestID": "6c37e2d5-92cc-4241-a9f8-9813720aec6",
    "authCode": null,
    "card": {
        "holder": "John Doe",
        "bin": "401200",
        "digit": "0085",
        "brand": "visa",
        "cardLevel": "CLASSIC",
        "expired": "12/2025",
        "maskNumber": "4012 00XX XXXX 0085"
    },
    "bank": null,
    "customerBank": null,
    "fees": null,
    "meta": null,
    "threeds": {
        "redirectUrl": "https://secure.paypipes.com/api/v2/card/threeds",
        "redirectParams": {
            "purchase_request_id": "4b99850b6a24fede48c38a5a41d59d20d53c3102"
        }
    }
}
 

Example response (400, Error response):


{
    "error": "Bad request",
    "code": 200000
}
 

Example response (401, Error response):


{
    "error": "Unauthenticated",
    "code": 100001
}
 

Example response (403, Error response):


{
    "error": "Unauthorized",
    "code": 100004
}
 

Example response (404, Error response):


{
    "error": "Record not found",
    "code": 200007
}
 

Example response (405, Error response):


{
    "error": "The specified method for the request is invalid",
    "code": 200008
}
 

Example response (410, Error response):


{
    "error": "Transaction has expired (Transaction ID: #ID)",
    "code": 200037
}
 

Example response (422, Error response):


{
    "error": "Transaction has invalid status: Pending",
    "code": 200013
}
 

Request      

POST api/v2/card/process

Headers

Authorization      

Example: Bearer {ACCESS_TOKEN}

Content-Type      

Example: application/json (or application/x-www-form-url-encoded)

Body Parameters

jwe   string   

A JWE (JSON Web Encryption) token containing the following encrypted JSON payload. The payload is encrypted using RSA-OAEP for key encryption and AES-256-GCM for content encryption. The public key used for encryption is obtained via a GET request to api/v2/public-jwk

{
   "purchase_request_id": string, Unique ID received by creating a request to purchase endpoint. Must be 40 characters. Example: b2685b95ec0de53d6871f836e3c90dca05fa1b44
  "pan": string, Primary Account Number (card number) used for the transaction. Example: 4111111111111111
  "exp": string, Card expiry date in MM/YY format. Example: 12/29
  "cvv": string, Card Verification Value – a 3- or 4-digit code printed on the card. Must be between 3 and 4 digits. Example: 123
  "holder": string, Name of the cardholder as printed on the card. Must be at least 2 characters. Must not be greater than 100 characters. Example: John Doe
  "timezone_offset": string, optional, Client device's timezone offset from UTC in minutes. Example: 540
  "screen_height": string, optional, Height of the user's screen in pixels. Example: 1080
  "screen_width": string, optional, Width of the user's screen in pixels. Example: 1920
  "screen_color_depth": string, optional, Color depth of the user's screen in bits. Example: 24
}

Example: eyJhbGciOiJ...

Response

Response Fields

Response 200      

Successful response

version   integer   

Indicates the version of the API. Example: 2

orderID   string   

Merchant's internal unique ID for the transaction. Example: ORD1234567890

trxID   string   

A unique identifier for the transaction. Example: 6c37e2d5-92cc-4241-a9f8-9813720aec64

trxType   string   

Specifies the type of the transaction. Allowed values: Purchase, Reverse, Refund. Example: Refund

amount   string   

The value representing the actual amount for the transaction. Format: DECIMAL(20,2) Example: 15.00

currency   string   

The currency code for the transaction, complies with the ISO 4217 standard. Example: EUR

status   string   

The current status of the transaction. Allowed values: Approved, Declined, Cancelled. Example: Approved

paymentStatus   string   

Additional status information regarding the payment, if available. Allowed values: Refunded, Partially refunded. Example: null

statusCode   string   

A code representing the detailed status of the transaction. Typically, this code is provided directly by the third-party gateway. In some instances, such as an internal error, an error code from our predefined list will be displayed. Example: 200

statusDescription   string   

A textual description of the status code. Example: Transaction has been refunded

declineCode   string   

Paypipes decline code. See Decline Codes table.

created   string   

The timestamp when the transaction was created. Example: 2024-06-04T10:50:38.000000Z

cardToken   string   

A token representing the customer's card information. Example: E75C608271E3852BA81A87540085

customerToken   string   

A token representing the customer. Example: 11cc649a-cdab-4b26-b9ec-781920174ca6

description   string   

A description of the transaction. Example: Refund transaction with ID #ORD1234567890

gateway   string   

The payment gateway used to process the transaction. Allowed values: Gateways Example: trustpay

applePay   boolean   

Indicates whether Apple Pay was used for the transaction. Example: false

googlePay   boolean   

Indicates whether Google Pay was used for the transaction. Example: false

refNo   string   

A reference number for the transaction, received from the third-party gateway. Example: null

requestID   string   

A unique identifier for the request associated with the transaction. This ID is sent to the third-party gateway. Example: 6c37e2d5-92cc-4241-a9f8-9813720aec6

authCode   string   

The authorization code for the transaction, if applicable. Example: null

card   Card   

Contains details about the card used for the transaction.

holder   string   

The name of the cardholder. Example: John Doe

bin   string   

The Bank Identification Number of the card. Example: 401200

digit   string   

The last four digits of the card number. Example: 0085

brand   string   

The brand of the card (e.g., Visa, Mastercard). Example: visa

cardLevel   string|null   

The level or type of the card. Example: CLASSIC

expired   string   

The expiration date of the card. Example: 12/2025

maskNumber   string   

The masked card number for security purposes. Example: 4012 00XX XXXX 0085

bank   Object   

Additional information about the bank account which was used for deposit. Example: null

customerBank   CustomerBank   

Contains detailed information about the customer's bank account.

bank_token   string   

A token identifying the bank account. Example: a6a6509b-26dc-49cc-b0e6-92c5d6eede36

customer_token   string   

A token identifying the customer who owns the bank account. Example: 496d8b1f-916e-4f79-bab6-a09a223ecffb

title   string   

The name of the bank account. Example: Bank Account

currency   string   

The currency code representing the currency in which the bank account is denominated. Example: USD

beneficiary_name   string   

The name of the account holder or the customer who owns the bank account. Example: John Doe

beneficiary_address   string   

The address of the account holder. Example: 123 Maple Street, London

bank_name   string   

The name of the bank where the customer's account is held. Example: Metro Bank

branch_name   string   

The name of the specific branch of the bank where the customer's account is maintained. Example: MetroBank

bank_address   string   

The address of the bank where the customer's account is held. Example: 123 Maple Street, London

bank_code   string   

The code that uniquely identifies the bank. Example: 0100

account_number   string   

The bank account number that uniquely identifies the customer's bank account. Example: 789456123

iban   string   

An international standard account number (IBAN) used to uniquely identify the customer's bank account for cross-border transactions. Example: GB23MBTC60161331926819

bic   string   

An international standard code (BIC/SWIFT) used to identify the customer's bank for cross-border transactions. Example: MBTCPHMMXXX

account_type   string   

The type of the bank account. Example: current

fees   Fee   

Contains details about any fees associated with the transaction. This object includes information such as the name, type, amount, and currency of the fee.

name   string   

The name of the fee. Example: Service Fee

type   string   

The type of the fee, indicating its purpose or category. Example: processing

amount   string   

The amount of the fee. Example: 50.00

currency   string   

The currency in which the fee amount is denominated. Example: USD

meta   Object   

Additional metadata related to the transaction, if available. Example: null

threeds   Object   

Contains data which are required for 3DS processing.

redirectUrl   string|null   

The URL to which the cardholder should be redirected to complete 3-D Secure authentication. Example: https://secure.paypipes.com/api/v2/card/threeds

redirectParams   object|null   

Key-value pairs of parameters to be sent along with the threeds request. Example: null

purchaseRequestId   string   

Unique ID received by creating a request to purchase endpoint. Example: 4b99850b6a24fede48c38a5a41d59d20d53c3102

Response 400|401|403|404|405|410|422      

Error response

error   string   

This parameter contains a message describing the error that occurred. Example: Invalid currency

code   integer   

This parameter provides a numeric code that uniquely identifies the specific error. Example: 100003

Card threeds

requires authentication

The card threeds endpoint is used for direct server-to-server 3DS processing by sending a POST request over HTTPS to the /card/threeds endpoint.

Example request:
curl --request POST \
    "https://secure.staging.paypipes.net/api/v2/card/threeds" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json (or application/x-www-form-url-encoded)" \
    --data "{
    \"purchase_request_id\": \"b2685b95ec0de53d6871f836e3c90dca05fa1b44\"
}"
const url = new URL(
    "https://secure.staging.paypipes.net/api/v2/card/threeds"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json (or application/x-www-form-url-encoded)",
    "Accept": "application/json",
};

let body = {
    "purchase_request_id": "b2685b95ec0de53d6871f836e3c90dca05fa1b44"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://secure.staging.paypipes.net/api/v2/card/threeds';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json (or application/x-www-form-url-encoded)',
        ],
        'json' => [
            'purchase_request_id' => 'b2685b95ec0de53d6871f836e3c90dca05fa1b44',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://secure.staging.paypipes.net/api/v2/card/threeds'
payload = {
    "purchase_request_id": "b2685b95ec0de53d6871f836e3c90dca05fa1b44"
}
headers = {
  'Authorization': 'Bearer {ACCESS_TOKEN}',
  'Content-Type': 'application/json (or application/x-www-form-url-encoded)'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (200, Successful response):


<!DOCTYPE html>
<html lang="en">

<head>
    <title>Redirecting ...</title>
    <script type="module" nonce="">
        document.addEventListener('DOMContentLoaded', function () {
            window.location.href = "https://authentication-devices.sandbox.checkout.com/sessions-interceptor/sid_l3qxbdli5mmevhz3tb4gzyysfi"
        });
    </script>
</head>

</html>
 

Example response (400, Error response):


{
    "error": "Bad request",
    "code": 200000
}
 

Example response (401, Error response):


{
    "error": "Unauthenticated",
    "code": 100001
}
 

Example response (403, Error response):


{
    "error": "Unauthorized",
    "code": 100004
}
 

Example response (404, Error response):


{
    "error": "Record not found",
    "code": 200007
}
 

Example response (405, Error response):


{
    "error": "The specified method for the request is invalid",
    "code": 200008
}
 

Example response (410, Error response):


{
    "error": "Transaction has expired (Transaction ID: #ID)",
    "code": 200037
}
 

Example response (422, Error response):


{
    "error": "Transaction has invalid status: Pending",
    "code": 200013
}
 

Request      

POST api/v2/card/threeds

Headers

Authorization      

Example: Bearer {ACCESS_TOKEN}

Content-Type      

Example: application/json (or application/x-www-form-url-encoded)

Body Parameters

purchase_request_id   string   

Unique ID received by creating a request to purchase endpoint. Must be 40 characters. Example: b2685b95ec0de53d6871f836e3c90dca05fa1b44

Response

Response Fields

Response 200   HTML   

Successful response

Response 400|401|403|404|405|410|422      

Error response

error   string   

This parameter contains a message describing the error that occurred. Example: Invalid currency

code   integer   

This parameter provides a numeric code that uniquely identifies the specific error. Example: 100003

Charge

requires authentication

The charge endpoint creates a transaction using the previous transaction ID by sending a POST request over HTTPS to the /charge endpoint. This triggers the creation of a new charge transaction.

Example request:
curl --request POST \
    "https://secure.staging.paypipes.net/api/v2/charge" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json (or application/x-www-form-url-encoded)" \
    --data "{
    \"order_id\": \"ORD1234567890\",
    \"transaction_id\": \"123e4567-e89b-12d3-a456-426614174000\",
    \"amount\": \"100.00\",
    \"currency\": \"USD\",
    \"description\": \"Payment for order ORD1234567890\"
}"
const url = new URL(
    "https://secure.staging.paypipes.net/api/v2/charge"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json (or application/x-www-form-url-encoded)",
    "Accept": "application/json",
};

let body = {
    "order_id": "ORD1234567890",
    "transaction_id": "123e4567-e89b-12d3-a456-426614174000",
    "amount": "100.00",
    "currency": "USD",
    "description": "Payment for order ORD1234567890"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://secure.staging.paypipes.net/api/v2/charge';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json (or application/x-www-form-url-encoded)',
        ],
        'json' => [
            'order_id' => 'ORD1234567890',
            'transaction_id' => '123e4567-e89b-12d3-a456-426614174000',
            'amount' => '100.00',
            'currency' => 'USD',
            'description' => 'Payment for order ORD1234567890',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://secure.staging.paypipes.net/api/v2/charge'
payload = {
    "order_id": "ORD1234567890",
    "transaction_id": "123e4567-e89b-12d3-a456-426614174000",
    "amount": "100.00",
    "currency": "USD",
    "description": "Payment for order ORD1234567890"
}
headers = {
  'Authorization': 'Bearer {ACCESS_TOKEN}',
  'Content-Type': 'application/json (or application/x-www-form-url-encoded)'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (200, Successful response):


{
    "version": 2,
    "orderID": "ORD1234567890",
    "trxID": "6c37e2d5-92cc-4241-a9f8-9813720aec64",
    "trxType": "Purchase",
    "amount": "15.00",
    "currency": "EUR",
    "status": "Waiting",
    "paymentStatus": null,
    "statusCode": "200",
    "statusDescription": "",
    "declineCode": null,
    "created": "2024-06-04T10:50:38.000000Z",
    "cardToken": "E75C608271E3852BA81A87540085",
    "customerToken": "11cc649a-cdab-4b26-b9ec-781920174ca6",
    "description": "Charge transaction with ID #ORD1234567890",
    "gateway": "ecommpay",
    "applePay": false,
    "googlePay": false,
    "refNo": null,
    "requestID": "6c37e2d5-92cc-4241-a9f8-9813720aec6",
    "authCode": null,
    "card": {
        "holder": "John Doe",
        "bin": "401200",
        "digit": "0085",
        "brand": "visa",
        "cardLevel": "CLASSIC",
        "expired": "12/2025",
        "maskNumber": "4012 00XX XXXX 0085"
    },
    "bank": null,
    "customerBank": null,
    "fees": null,
    "meta": null
}
 

Example response (400, Error response):


{
    "error": "Bad request",
    "code": 200000
}
 

Example response (401, Error response):


{
    "error": "Unauthenticated",
    "code": 100001
}
 

Example response (403, Error response):


{
    "error": "Unauthorized",
    "code": 100004
}
 

Example response (404, Error response):


{
    "error": "Record not found",
    "code": 200007
}
 

Example response (405, Error response):


{
    "error": "The specified method for the request is invalid",
    "code": 200008
}
 

Example response (410, Error response):


{
    "error": "Transaction has expired (Transaction ID: #ID)",
    "code": 200037
}
 

Example response (422, Error response):


{
    "error": "Transaction has invalid status: Pending",
    "code": 200013
}
 

Request      

POST api/v2/charge

Headers

Authorization      

Example: Bearer {ACCESS_TOKEN}

Content-Type      

Example: application/json (or application/x-www-form-url-encoded)

Body Parameters

order_id   string   

Merchant's internal unique ID for the transaction. Must be at least 1 character. Must not be greater than 40 characters. Example: ORD1234567890

transaction_id   string   

ID referencing the purchase transaction. The transaction_id of an existing record in the transactions table. Must be 36 characters. Example: 123e4567-e89b-12d3-a456-426614174000

amount   string   

The value representing the actual amount for the transaction. The decimal points must match the currency's decimal point length. For example, for USD currency, valid amounts include "5.99", "6.00", or "6". An amount like "5.995" would throw a validation error due to an invalid amount specified. Must not be greater than 10 characters. Example: 100.00

currency   string   

The currency code for the transaction, which must comply with the ISO 4217 standard and be represented by a three-letter code. The cy_code of an existing record in the currencies table. Example: USD

description   string   

A description of the transaction. Must not be greater than 255 characters. Must be at least 5 characters. Example: Payment for order ORD1234567890

Response

Response Fields

Response 200      

Successful response

version   integer   

Indicates the version of the API. Example: 2

orderID   string   

Merchant's internal unique ID for the transaction. Example: ORD1234567890

trxID   string   

A unique identifier for the transaction. Example: 6c37e2d5-92cc-4241-a9f8-9813720aec64

trxType   string   

Specifies the type of the transaction. Allowed values: Purchase, Reverse, Refund. Example: Refund

amount   string   

The value representing the actual amount for the transaction. Format: DECIMAL(20,2) Example: 15.00

currency   string   

The currency code for the transaction, complies with the ISO 4217 standard. Example: EUR

status   string   

The current status of the transaction. Allowed values: Approved, Declined, Cancelled. Example: Approved

paymentStatus   string   

Additional status information regarding the payment, if available. Allowed values: Refunded, Partially refunded. Example: null

statusCode   string   

A code representing the detailed status of the transaction. Typically, this code is provided directly by the third-party gateway. In some instances, such as an internal error, an error code from our predefined list will be displayed. Example: 200

statusDescription   string   

A textual description of the status code. Example: Transaction has been refunded

declineCode   string   

Paypipes decline code. See Decline Codes table.

created   string   

The timestamp when the transaction was created. Example: 2024-06-04T10:50:38.000000Z

cardToken   string   

A token representing the customer's card information. Example: E75C608271E3852BA81A87540085

customerToken   string   

A token representing the customer. Example: 11cc649a-cdab-4b26-b9ec-781920174ca6

description   string   

A description of the transaction. Example: Refund transaction with ID #ORD1234567890

gateway   string   

The payment gateway used to process the transaction. Allowed values: Gateways Example: trustpay

applePay   boolean   

Indicates whether Apple Pay was used for the transaction. Example: false

googlePay   boolean   

Indicates whether Google Pay was used for the transaction. Example: false

refNo   string   

A reference number for the transaction, received from the third-party gateway. Example: null

requestID   string   

A unique identifier for the request associated with the transaction. This ID is sent to the third-party gateway. Example: 6c37e2d5-92cc-4241-a9f8-9813720aec6

authCode   string   

The authorization code for the transaction, if applicable. Example: null

card   Card   

Contains details about the card used for the transaction.

holder   string   

The name of the cardholder. Example: John Doe

bin   string   

The Bank Identification Number of the card. Example: 401200

digit   string   

The last four digits of the card number. Example: 0085

brand   string   

The brand of the card (e.g., Visa, Mastercard). Example: visa

cardLevel   string|null   

The level or type of the card. Example: CLASSIC

expired   string   

The expiration date of the card. Example: 12/2025

maskNumber   string   

The masked card number for security purposes. Example: 4012 00XX XXXX 0085

bank   Object   

Additional information about the bank account which was used for deposit. Example: null

customerBank   CustomerBank   

Contains detailed information about the customer's bank account.

bank_token   string   

A token identifying the bank account. Example: a6a6509b-26dc-49cc-b0e6-92c5d6eede36

customer_token   string   

A token identifying the customer who owns the bank account. Example: 496d8b1f-916e-4f79-bab6-a09a223ecffb

title   string   

The name of the bank account. Example: Bank Account

currency   string   

The currency code representing the currency in which the bank account is denominated. Example: USD

beneficiary_name   string   

The name of the account holder or the customer who owns the bank account. Example: John Doe

beneficiary_address   string   

The address of the account holder. Example: 123 Maple Street, London

bank_name   string   

The name of the bank where the customer's account is held. Example: Metro Bank

branch_name   string   

The name of the specific branch of the bank where the customer's account is maintained. Example: MetroBank

bank_address   string   

The address of the bank where the customer's account is held. Example: 123 Maple Street, London

bank_code   string   

The code that uniquely identifies the bank. Example: 0100

account_number   string   

The bank account number that uniquely identifies the customer's bank account. Example: 789456123

iban   string   

An international standard account number (IBAN) used to uniquely identify the customer's bank account for cross-border transactions. Example: GB23MBTC60161331926819

bic   string   

An international standard code (BIC/SWIFT) used to identify the customer's bank for cross-border transactions. Example: MBTCPHMMXXX

account_type   string   

The type of the bank account. Example: current

bank_clearing_system_code   string   

The bank clearing code (ISO 20022). Example: SGIBG

bank_clearing_system_id   string   

The bank clearing identifier (ISO 20022). Example: 1234567

fees   Fee   

Contains details about any fees associated with the transaction. This object includes information such as the name, type, amount, and currency of the fee.

name   string   

The name of the fee. Example: Service Fee

type   string   

The type of the fee, indicating its purpose or category. Example: processing

amount   string   

The amount of the fee. Example: 50.00

currency   string   

The currency in which the fee amount is denominated. Example: USD

meta   Object   

Additional metadata related to the transaction, if available. Example: null

Response 400|401|403|404|405|410|422      

Error response

error   string   

This parameter contains a message describing the error that occurred. Example: Invalid currency

code   integer   

This parameter provides a numeric code that uniquely identifies the specific error. Example: 100003

Charge cancel

requires authentication

The charge cancel endpoint creates a transaction using the previous transaction ID by sending a POST request over HTTPS to the /charge endpoint. This action cancels the ability to reuse the transaction ID for future charge transactions.

Example request:
curl --request POST \
    "https://secure.staging.paypipes.net/api/v2/charge/cancel" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json (or application/x-www-form-url-encoded)" \
    --data "{
    \"order_id\": \"ORD1234567890\",
    \"transaction_id\": \"123e4567-e89b-12d3-a456-426614174000\"
}"
const url = new URL(
    "https://secure.staging.paypipes.net/api/v2/charge/cancel"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json (or application/x-www-form-url-encoded)",
    "Accept": "application/json",
};

let body = {
    "order_id": "ORD1234567890",
    "transaction_id": "123e4567-e89b-12d3-a456-426614174000"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://secure.staging.paypipes.net/api/v2/charge/cancel';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json (or application/x-www-form-url-encoded)',
        ],
        'json' => [
            'order_id' => 'ORD1234567890',
            'transaction_id' => '123e4567-e89b-12d3-a456-426614174000',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://secure.staging.paypipes.net/api/v2/charge/cancel'
payload = {
    "order_id": "ORD1234567890",
    "transaction_id": "123e4567-e89b-12d3-a456-426614174000"
}
headers = {
  'Authorization': 'Bearer {ACCESS_TOKEN}',
  'Content-Type': 'application/json (or application/x-www-form-url-encoded)'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (200, Successful response):


{
    "version": 2,
    "orderID": "ORD1234567890",
    "trxID": "6c37e2d5-92cc-4241-a9f8-9813720aec64",
    "trxType": "Cancel",
    "amount": "15.00",
    "currency": "EUR",
    "status": "Waiting",
    "paymentStatus": null,
    "statusCode": "200",
    "statusDescription": "",
    "declineCode": null,
    "created": "2024-06-04T10:50:38.000000Z",
    "cardToken": "E75C608271E3852BA81A87540085",
    "customerToken": "11cc649a-cdab-4b26-b9ec-781920174ca6",
    "description": "Charge cancel transaction with ID #ORD1234567890",
    "gateway": "ecommpay",
    "applePay": false,
    "googlePay": false,
    "refNo": null,
    "requestID": "6c37e2d5-92cc-4241-a9f8-9813720aec6",
    "authCode": null,
    "card": {
        "holder": "John Doe",
        "bin": "401200",
        "digit": "0085",
        "brand": "visa",
        "cardLevel": "CLASSIC",
        "expired": "12/2025",
        "maskNumber": "4012 00XX XXXX 0085"
    },
    "bank": null,
    "customerBank": null,
    "fees": null,
    "meta": null
}
 

Example response (400, Error response):


{
    "error": "Bad request",
    "code": 200000
}
 

Example response (401, Error response):


{
    "error": "Unauthenticated",
    "code": 100001
}
 

Example response (403, Error response):


{
    "error": "Unauthorized",
    "code": 100004
}
 

Example response (404, Error response):


{
    "error": "Record not found",
    "code": 200007
}
 

Example response (405, Error response):


{
    "error": "The specified method for the request is invalid",
    "code": 200008
}
 

Example response (410, Error response):


{
    "error": "Transaction has expired (Transaction ID: #ID)",
    "code": 200037
}
 

Example response (422, Error response):


{
    "error": "Transaction has invalid status: Pending",
    "code": 200013
}
 

Request      

POST api/v2/charge/cancel

Headers

Authorization      

Example: Bearer {ACCESS_TOKEN}

Content-Type      

Example: application/json (or application/x-www-form-url-encoded)

Body Parameters

order_id   string   

Merchant's internal unique ID for the transaction. Must be at least 1 character. Must not be greater than 40 characters. Example: ORD1234567890

transaction_id   string   

ID referencing the purchase transaction. The transaction_id of an existing record in the transactions table. Must be 36 characters. Example: 123e4567-e89b-12d3-a456-426614174000

Response

Response Fields

Response 200      

Successful response

version   integer   

Indicates the version of the API. Example: 2

orderID   string   

Merchant's internal unique ID for the transaction. Example: ORD1234567890

trxID   string   

A unique identifier for the transaction. Example: 6c37e2d5-92cc-4241-a9f8-9813720aec64

trxType   string   

Specifies the type of the transaction. Allowed values: Purchase, Reverse, Refund. Example: Refund

amount   string   

The value representing the actual amount for the transaction. Format: DECIMAL(20,2) Example: 15.00

currency   string   

The currency code for the transaction, complies with the ISO 4217 standard. Example: EUR

status   string   

The current status of the transaction. Allowed values: Approved, Declined, Cancelled. Example: Approved

paymentStatus   string   

Additional status information regarding the payment, if available. Allowed values: Refunded, Partially refunded. Example: null

statusCode   string   

A code representing the detailed status of the transaction. Typically, this code is provided directly by the third-party gateway. In some instances, such as an internal error, an error code from our predefined list will be displayed. Example: 200

statusDescription   string   

A textual description of the status code. Example: Transaction has been refunded

declineCode   string   

Paypipes decline code. See Decline Codes table.

created   string   

The timestamp when the transaction was created. Example: 2024-06-04T10:50:38.000000Z

cardToken   string   

A token representing the customer's card information. Example: E75C608271E3852BA81A87540085

customerToken   string   

A token representing the customer. Example: 11cc649a-cdab-4b26-b9ec-781920174ca6

description   string   

A description of the transaction. Example: Refund transaction with ID #ORD1234567890

gateway   string   

The payment gateway used to process the transaction. Allowed values: Gateways Example: trustpay

applePay   boolean   

Indicates whether Apple Pay was used for the transaction. Example: false

googlePay   boolean   

Indicates whether Google Pay was used for the transaction. Example: false

refNo   string   

A reference number for the transaction, received from the third-party gateway. Example: null

requestID   string   

A unique identifier for the request associated with the transaction. This ID is sent to the third-party gateway. Example: 6c37e2d5-92cc-4241-a9f8-9813720aec6

authCode   string   

The authorization code for the transaction, if applicable. Example: null

card   Card   

Contains details about the card used for the transaction.

holder   string   

The name of the cardholder. Example: John Doe

bin   string   

The Bank Identification Number of the card. Example: 401200

digit   string   

The last four digits of the card number. Example: 0085

brand   string   

The brand of the card (e.g., Visa, Mastercard). Example: visa

cardLevel   string|null   

The level or type of the card. Example: CLASSIC

expired   string   

The expiration date of the card. Example: 12/2025

maskNumber   string   

The masked card number for security purposes. Example: 4012 00XX XXXX 0085

bank   Object   

Additional information about the bank account which was used for deposit. Example: null

customerBank   CustomerBank   

Contains detailed information about the customer's bank account.

bank_token   string   

A token identifying the bank account. Example: a6a6509b-26dc-49cc-b0e6-92c5d6eede36

customer_token   string   

A token identifying the customer who owns the bank account. Example: 496d8b1f-916e-4f79-bab6-a09a223ecffb

title   string   

The name of the bank account. Example: Bank Account

currency   string   

The currency code representing the currency in which the bank account is denominated. Example: USD

beneficiary_name   string   

The name of the account holder or the customer who owns the bank account. Example: John Doe

beneficiary_address   string   

The address of the account holder. Example: 123 Maple Street, London

bank_name   string   

The name of the bank where the customer's account is held. Example: Metro Bank

branch_name   string   

The name of the specific branch of the bank where the customer's account is maintained. Example: MetroBank

bank_address   string   

The address of the bank where the customer's account is held. Example: 123 Maple Street, London

bank_code   string   

The code that uniquely identifies the bank. Example: 0100

account_number   string   

The bank account number that uniquely identifies the customer's bank account. Example: 789456123

iban   string   

An international standard account number (IBAN) used to uniquely identify the customer's bank account for cross-border transactions. Example: GB23MBTC60161331926819

bic   string   

An international standard code (BIC/SWIFT) used to identify the customer's bank for cross-border transactions. Example: MBTCPHMMXXX

account_type   string   

The type of the bank account. Example: current

bank_clearing_system_code   string   

The bank clearing code (ISO 20022). Example: SGIBG

bank_clearing_system_id   string   

The bank clearing identifier (ISO 20022). Example: 1234567

fees   Fee   

Contains details about any fees associated with the transaction. This object includes information such as the name, type, amount, and currency of the fee.

name   string   

The name of the fee. Example: Service Fee

type   string   

The type of the fee, indicating its purpose or category. Example: processing

amount   string   

The amount of the fee. Example: 50.00

currency   string   

The currency in which the fee amount is denominated. Example: USD

meta   Object   

Additional metadata related to the transaction, if available. Example: null

Response 400|401|403|404|405|410|422      

Error response

error   string   

This parameter contains a message describing the error that occurred. Example: Invalid currency

code   integer   

This parameter provides a numeric code that uniquely identifies the specific error. Example: 100003

Reverse

requires authentication

Some payment gateways support a reverse endpoint that works like a payment cancellation, offering potential fee benefits. Unlike a refund, you can only reverse the entire transaction.

Example request:
curl --request POST \
    "https://secure.staging.paypipes.net/api/v2/reverse" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json (or application/x-www-form-url-encoded)" \
    --data "{
    \"transaction_id\": \"123e4567-e89b-12d3-a456-426614174000\",
    \"order_id\": \"ORD1234567890\",
    \"description\": \"Reverse transaction with ID #ORD1234567890\",
    \"callback_url\": \"https:\\/\\/example.com\\/callback\",
    \"execution_date\": \"2024-07-01T14:30:00Z\"
}"
const url = new URL(
    "https://secure.staging.paypipes.net/api/v2/reverse"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json (or application/x-www-form-url-encoded)",
    "Accept": "application/json",
};

let body = {
    "transaction_id": "123e4567-e89b-12d3-a456-426614174000",
    "order_id": "ORD1234567890",
    "description": "Reverse transaction with ID #ORD1234567890",
    "callback_url": "https:\/\/example.com\/callback",
    "execution_date": "2024-07-01T14:30:00Z"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://secure.staging.paypipes.net/api/v2/reverse';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json (or application/x-www-form-url-encoded)',
        ],
        'json' => [
            'transaction_id' => '123e4567-e89b-12d3-a456-426614174000',
            'order_id' => 'ORD1234567890',
            'description' => 'Reverse transaction with ID #ORD1234567890',
            'callback_url' => 'https://example.com/callback',
            'execution_date' => '2024-07-01T14:30:00Z',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://secure.staging.paypipes.net/api/v2/reverse'
payload = {
    "transaction_id": "123e4567-e89b-12d3-a456-426614174000",
    "order_id": "ORD1234567890",
    "description": "Reverse transaction with ID #ORD1234567890",
    "callback_url": "https:\/\/example.com\/callback",
    "execution_date": "2024-07-01T14:30:00Z"
}
headers = {
  'Authorization': 'Bearer {ACCESS_TOKEN}',
  'Content-Type': 'application/json (or application/x-www-form-url-encoded)'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (200, Successful response):


{
    "version": 2,
    "orderID": "ORD1234567890",
    "trxID": "6c37e2d5-92cc-4241-a9f8-9813720aec64",
    "trxType": "Reverse",
    "amount": "15.00",
    "currency": "EUR",
    "status": "Approved",
    "paymentStatus": null,
    "statusCode": "200",
    "statusDescription": "Transaction has been reversed",
    "declineCode": null,
    "created": "2024-06-04T10:50:38.000000Z",
    "cardToken": "E75C608271E3852BA81A87540085",
    "customerToken": "11cc649a-cdab-4b26-b9ec-781920174ca6",
    "description": "Reverse transaction with ID #ORD1234567890",
    "gateway": "trustpay",
    "applePay": false,
    "googlePay": false,
    "refNo": null,
    "requestID": "6c37e2d5-92cc-4241-a9f8-9813720aec6",
    "authCode": null,
    "card": {
        "holder": "John Doe",
        "bin": "401200",
        "digit": "0085",
        "brand": "visa",
        "cardLevel": "CLASSIC",
        "expired": "12/2025",
        "maskNumber": "4012 00XX XXXX 0085"
    },
    "bank": null,
    "customerBank": null,
    "fees": null,
    "meta": null
}
 

Example response (400, Error response):


{
    "error": "Bad request",
    "code": 200000
}
 

Example response (401, Error response):


{
    "error": "Unauthenticated",
    "code": 100001
}
 

Example response (403, Error response):


{
    "error": "Unauthorized",
    "code": 100004
}
 

Example response (404, Error response):


{
    "error": "Record not found",
    "code": 200007
}
 

Example response (405, Error response):


{
    "error": "The specified method for the request is invalid",
    "code": 200008
}
 

Example response (410, Error response):


{
    "error": "Transaction has expired (Transaction ID: #ID)",
    "code": 200037
}
 

Example response (422, Error response):


{
    "error": "Transaction has invalid status: Pending",
    "code": 200013
}
 

Request      

POST api/v2/reverse

Headers

Authorization      

Example: Bearer {ACCESS_TOKEN}

Content-Type      

Example: application/json (or application/x-www-form-url-encoded)

Body Parameters

transaction_id   string   

ID referencing the purchase transaction to be refunded. The transaction_id of an existing record in the transactions table. Must be 36 characters. Example: 123e4567-e89b-12d3-a456-426614174000

order_id   string  optional  

Merchant's internal unique ID for the transaction. Must not be greater than 40 characters. Must be at least 1 character. Example: ORD1234567890

description   string   

Description of the transaction. Must not be greater than 255 characters. Must be at least 5 characters. Example: Reverse transaction with ID #ORD1234567890

callback_url   string  optional  

URL used to receive callback notification with information about the transaction. Must be a valid URL. Must not be greater than 2048 characters. Example: https://example.com/callback

execution_date   string  optional  

Date and time indicating when the transaction should be executed. Must be in the future. If this value is not present, transaction will be executed immediately. Must be a valid date. Must be a valid date in the format Y-m-d\TH:i:s\Z. Example: 2024-07-01T14:30:00Z

Response

Response Fields

Response 200      

Successful response

version   integer   

Indicates the version of the API. Example: 2

orderID   string   

Merchant's internal unique ID for the transaction. Example: ORD1234567890

trxID   string   

A unique identifier for the transaction. Example: 6c37e2d5-92cc-4241-a9f8-9813720aec64

trxType   string   

Specifies the type of the transaction. Allowed values: Purchase, Reverse, Refund. Example: Reverse

amount   string   

The value representing the actual amount for the transaction. Format: DECIMAL(20,2) Example: 15.00

currency   string   

The currency code for the transaction, complies with the ISO 4217 standard. Example: EUR

status   string   

The current status of the transaction. Allowed values: Approved, Declined, Cancelled. Example: Approved

paymentStatus   string   

Additional status information regarding the payment, if available. Allowed values: Refunded, Partially refunded. Example: null

statusCode   string   

A code representing the detailed status of the transaction. Typically, this code is provided directly by the third-party gateway. In some instances, such as an internal error, an error code from our predefined list will be displayed. Example: 200

statusDescription   string   

A textual description of the status code. Example: Transaction has been reversed

declineCode   string   

Paypipes decline code. See Decline Codes table.

created   string   

The timestamp when the transaction was created. Example: 2024-06-04T10:50:38.000000Z

cardToken   string   

A token representing the customer's card information. Example: E75C608271E3852BA81A87540085

customerToken   string   

A token representing the customer. Example: 11cc649a-cdab-4b26-b9ec-781920174ca6

description   string   

A description of the transaction. Example: Reverse transaction with ID #ORD1234567890

gateway   string   

The payment gateway used to process the transaction. Allowed values: Gateways Example: trustpay

applePay   boolean   

Indicates whether Apple Pay was used for the transaction. Example: false

googlePay   boolean   

Indicates whether Google Pay was used for the transaction. Example: false

refNo   string   

A reference number for the transaction, received from the third-party gateway. Example: null

requestID   string   

A unique identifier for the request associated with the transaction. This ID is sent to the third-party gateway. Example: 6c37e2d5-92cc-4241-a9f8-9813720aec6

authCode   string   

The authorization code for the transaction, if applicable. Example: null

card   Card   

Contains details about the card used for the transaction.

holder   string   

The name of the cardholder. Example: John Doe

bin   string   

The Bank Identification Number of the card. Example: 401200

digit   string   

The last four digits of the card number. Example: 0085

brand   string   

The brand of the card (e.g., Visa, Mastercard). Example: visa

cardLevel   string|null   

The level or type of the card. Example: CLASSIC

expired   string   

The expiration date of the card. Example: 12/2025

maskNumber   string   

The masked card number for security purposes. Example: 4012 00XX XXXX 0085

bank   Object   

Additional information about the bank account which was used for deposit. Example: null

customerBank   CustomerBank   

Contains detailed information about the customer's bank account.

bank_token   string   

A token identifying the bank account. Example: a6a6509b-26dc-49cc-b0e6-92c5d6eede36

customer_token   string   

A token identifying the customer who owns the bank account. Example: 496d8b1f-916e-4f79-bab6-a09a223ecffb

title   string   

The name of the bank account. Example: Bank Account

currency   string   

The currency code representing the currency in which the bank account is denominated. Example: USD

beneficiary_name   string   

The name of the account holder or the customer who owns the bank account. Example: John Doe

beneficiary_address   string   

The address of the account holder. Example: 123 Maple Street, London

bank_name   string   

The name of the bank where the customer's account is held. Example: Metro Bank

branch_name   string   

The name of the specific branch of the bank where the customer's account is maintained. Example: MetroBank

bank_address   string   

The address of the bank where the customer's account is held. Example: 123 Maple Street, London

bank_code   string   

The code that uniquely identifies the bank. Example: 0100

account_number   string   

The bank account number that uniquely identifies the customer's bank account. Example: 789456123

iban   string   

An international standard account number (IBAN) used to uniquely identify the customer's bank account for cross-border transactions. Example: GB23MBTC60161331926819

bic   string   

An international standard code (BIC/SWIFT) used to identify the customer's bank for cross-border transactions. Example: MBTCPHMMXXX

account_type   string   

The type of the bank account. Example: current

bank_clearing_system_code   string   

The bank clearing code (ISO 20022). Example: SGIBG

bank_clearing_system_id   string   

The bank clearing identifier (ISO 20022). Example: 1234567

fees   Fee   

Contains details about any fees associated with the transaction. This object includes information such as the name, type, amount, and currency of the fee.

name   string   

The name of the fee. Example: Service Fee

type   string   

The type of the fee, indicating its purpose or category. Example: processing

amount   string   

The amount of the fee. Example: 50.00

currency   string   

The currency in which the fee amount is denominated. Example: USD

meta   Object   

Additional metadata related to the transaction, if available. Example: null

Response 400|401|403|404|405|410|422      

Error response

error   string   

This parameter contains a message describing the error that occurred. Example: Invalid currency

code   integer   

This parameter provides a numeric code that uniquely identifies the specific error. Example: 100003

Refund

requires authentication

Refunds are available for card processing gateways. You can trigger a full or partial refund through the API or our back office.

Example request:
curl --request POST \
    "https://secure.staging.paypipes.net/api/v2/refund" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json (or application/x-www-form-url-encoded)" \
    --data "{
    \"transaction_id\": \"123e4567-e89b-12d3-a456-426614174000\",
    \"order_id\": \"ORD1234567890\",
    \"description\": \"Refund transaction with ID #ORD1234567890\",
    \"amount\": \"25.00\",
    \"callback_url\": \"https:\\/\\/example.com\\/callback\",
    \"execution_date\": \"2024-07-01T14:30:00Z\"
}"
const url = new URL(
    "https://secure.staging.paypipes.net/api/v2/refund"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json (or application/x-www-form-url-encoded)",
    "Accept": "application/json",
};

let body = {
    "transaction_id": "123e4567-e89b-12d3-a456-426614174000",
    "order_id": "ORD1234567890",
    "description": "Refund transaction with ID #ORD1234567890",
    "amount": "25.00",
    "callback_url": "https:\/\/example.com\/callback",
    "execution_date": "2024-07-01T14:30:00Z"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://secure.staging.paypipes.net/api/v2/refund';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json (or application/x-www-form-url-encoded)',
        ],
        'json' => [
            'transaction_id' => '123e4567-e89b-12d3-a456-426614174000',
            'order_id' => 'ORD1234567890',
            'description' => 'Refund transaction with ID #ORD1234567890',
            'amount' => '25.00',
            'callback_url' => 'https://example.com/callback',
            'execution_date' => '2024-07-01T14:30:00Z',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://secure.staging.paypipes.net/api/v2/refund'
payload = {
    "transaction_id": "123e4567-e89b-12d3-a456-426614174000",
    "order_id": "ORD1234567890",
    "description": "Refund transaction with ID #ORD1234567890",
    "amount": "25.00",
    "callback_url": "https:\/\/example.com\/callback",
    "execution_date": "2024-07-01T14:30:00Z"
}
headers = {
  'Authorization': 'Bearer {ACCESS_TOKEN}',
  'Content-Type': 'application/json (or application/x-www-form-url-encoded)'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (200, Successful response):


{
    "version": 2,
    "orderID": "ORD1234567890",
    "trxID": "6c37e2d5-92cc-4241-a9f8-9813720aec64",
    "trxType": "Refund",
    "amount": "15.00",
    "currency": "EUR",
    "status": "Approved",
    "paymentStatus": null,
    "statusCode": "200",
    "statusDescription": "Transaction has been refunded",
    "declineCode": null,
    "created": "2024-06-04T10:50:38.000000Z",
    "cardToken": "E75C608271E3852BA81A87540085",
    "customerToken": "11cc649a-cdab-4b26-b9ec-781920174ca6",
    "description": "Refund transaction with ID #ORD1234567890",
    "gateway": "trustpay",
    "applePay": false,
    "googlePay": false,
    "refNo": null,
    "requestID": "6c37e2d5-92cc-4241-a9f8-9813720aec6",
    "authCode": null,
    "card": {
        "holder": "John Doe",
        "bin": "401200",
        "digit": "0085",
        "brand": "visa",
        "cardLevel": "CLASSIC",
        "expired": "12/2025",
        "maskNumber": "4012 00XX XXXX 0085"
    },
    "bank": null,
    "customerBank": null,
    "fees": null,
    "meta": null
}
 

Example response (400, Error response):


{
    "error": "Bad request",
    "code": 200000
}
 

Example response (401, Error response):


{
    "error": "Unauthenticated",
    "code": 100001
}
 

Example response (403, Error response):


{
    "error": "Unauthorized",
    "code": 100004
}
 

Example response (404, Error response):


{
    "error": "Record not found",
    "code": 200007
}
 

Example response (405, Error response):


{
    "error": "The specified method for the request is invalid",
    "code": 200008
}
 

Example response (410, Error response):


{
    "error": "Transaction has expired (Transaction ID: #ID)",
    "code": 200037
}
 

Example response (422, Error response):


{
    "error": "Transaction has invalid status: Pending",
    "code": 200013
}
 

Request      

POST api/v2/refund

Headers

Authorization      

Example: Bearer {ACCESS_TOKEN}

Content-Type      

Example: application/json (or application/x-www-form-url-encoded)

Body Parameters

transaction_id   string   

ID referencing the purchase transaction to be refunded. The transaction_id of an existing record in the transactions table. Must be 36 characters. Example: 123e4567-e89b-12d3-a456-426614174000

order_id   string  optional  

Merchant's internal unique ID for the transaction. Must not be greater than 40 characters. Must be at least 1 character. Example: ORD1234567890

description   string   

Description of the transaction. Must not be greater than 255 characters. Must be at least 5 characters. Example: Refund transaction with ID #ORD1234567890

amount   string   

The amount to be refunded should be equal to or less than the amount of the original purchase transaction. The decimal points must match the currency's decimal point length. For example, for USD currency valid amounts include "5.99", "6.00", or "6". An amount like "5.995" would throw a validation errordue to an invalid amount specified. Must not be greater than 10 characters. Example: 25.00

callback_url   string  optional  

URL used to receive callback notification with information about the transaction. Must be a valid URL. Must not be greater than 2048 characters. Example: https://example.com/callback

execution_date   string  optional  

Date and time indicating when the transaction should be executed. Must be in the future. If this value is not present, transaction will be executed immediately. Must be a valid date. Must be a valid date in the format Y-m-d\TH:i:s\Z. Example: 2024-07-01T14:30:00Z

Response

Response Fields

Response 200      

Successful response

version   integer   

Indicates the version of the API. Example: 2

orderID   string   

Merchant's internal unique ID for the transaction. Example: ORD1234567890

trxID   string   

A unique identifier for the transaction. Example: 6c37e2d5-92cc-4241-a9f8-9813720aec64

trxType   string   

Specifies the type of the transaction. Allowed values: Purchase, Reverse, Refund. Example: Refund

amount   string   

The value representing the actual amount for the transaction. Format: DECIMAL(20,2) Example: 15.00

currency   string   

The currency code for the transaction, complies with the ISO 4217 standard. Example: EUR

status   string   

The current status of the transaction. Allowed values: Approved, Declined, Cancelled. Example: Approved

paymentStatus   string   

Additional status information regarding the payment, if available. Allowed values: Refunded, Partially refunded. Example: null

statusCode   string   

A code representing the detailed status of the transaction. Typically, this code is provided directly by the third-party gateway. In some instances, such as an internal error, an error code from our predefined list will be displayed. Example: 200

statusDescription   string   

A textual description of the status code. Example: Transaction has been refunded

declineCode   string   

Paypipes decline code. See Decline Codes table.

created   string   

The timestamp when the transaction was created. Example: 2024-06-04T10:50:38.000000Z

cardToken   string   

A token representing the customer's card information. Example: E75C608271E3852BA81A87540085

customerToken   string   

A token representing the customer. Example: 11cc649a-cdab-4b26-b9ec-781920174ca6

description   string   

A description of the transaction. Example: Refund transaction with ID #ORD1234567890

gateway   string   

The payment gateway used to process the transaction. Allowed values: Gateways Example: trustpay

applePay   boolean   

Indicates whether Apple Pay was used for the transaction. Example: false

googlePay   boolean   

Indicates whether Google Pay was used for the transaction. Example: false

refNo   string   

A reference number for the transaction, received from the third-party gateway. Example: null

requestID   string   

A unique identifier for the request associated with the transaction. This ID is sent to the third-party gateway. Example: 6c37e2d5-92cc-4241-a9f8-9813720aec6

authCode   string   

The authorization code for the transaction, if applicable. Example: null

card   Card   

Contains details about the card used for the transaction.

holder   string   

The name of the cardholder. Example: John Doe

bin   string   

The Bank Identification Number of the card. Example: 401200

digit   string   

The last four digits of the card number. Example: 0085

brand   string   

The brand of the card (e.g., Visa, Mastercard). Example: visa

cardLevel   string|null   

The level or type of the card. Example: CLASSIC

expired   string   

The expiration date of the card. Example: 12/2025

maskNumber   string   

The masked card number for security purposes. Example: 4012 00XX XXXX 0085

bank   Object   

Additional information about the bank account which was used for deposit. Example: null

customerBank   CustomerBank   

Contains detailed information about the customer's bank account.

bank_token   string   

A token identifying the bank account. Example: a6a6509b-26dc-49cc-b0e6-92c5d6eede36

customer_token   string   

A token identifying the customer who owns the bank account. Example: 496d8b1f-916e-4f79-bab6-a09a223ecffb

title   string   

The name of the bank account. Example: Bank Account

currency   string   

The currency code representing the currency in which the bank account is denominated. Example: USD

beneficiary_name   string   

The name of the account holder or the customer who owns the bank account. Example: John Doe

beneficiary_address   string   

The address of the account holder. Example: 123 Maple Street, London

bank_name   string   

The name of the bank where the customer's account is held. Example: Metro Bank

branch_name   string   

The name of the specific branch of the bank where the customer's account is maintained. Example: MetroBank

bank_address   string   

The address of the bank where the customer's account is held. Example: 123 Maple Street, London

bank_code   string   

The code that uniquely identifies the bank. Example: 0100

account_number   string   

The bank account number that uniquely identifies the customer's bank account. Example: 789456123

iban   string   

An international standard account number (IBAN) used to uniquely identify the customer's bank account for cross-border transactions. Example: GB23MBTC60161331926819

bic   string   

An international standard code (BIC/SWIFT) used to identify the customer's bank for cross-border transactions. Example: MBTCPHMMXXX

account_type   string   

The type of the bank account. Example: current

bank_clearing_system_code   string   

The bank clearing code (ISO 20022). Example: SGIBG

bank_clearing_system_id   string   

The bank clearing identifier (ISO 20022). Example: 1234567

fees   Fee   

Contains details about any fees associated with the transaction. This object includes information such as the name, type, amount, and currency of the fee.

name   string   

The name of the fee. Example: Service Fee

type   string   

The type of the fee, indicating its purpose or category. Example: processing

amount   string   

The amount of the fee. Example: 50.00

currency   string   

The currency in which the fee amount is denominated. Example: USD

meta   Object   

Additional metadata related to the transaction, if available. Example: null

Response 400|401|403|404|405|410|422      

Error response

error   string   

This parameter contains a message describing the error that occurred. Example: Invalid currency

code   integer   

This parameter provides a numeric code that uniquely identifies the specific error. Example: 100003

Status of transactions

requires authentication

To get information about the current status of transactions, call the status endpoint with the transaction_id, order_id or purchase_request_id. This endpoint returns an array of transactions.

Example request:
curl --request POST \
    "https://secure.staging.paypipes.net/api/v2/transaction" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json (or application/x-www-form-url-encoded)" \
const url = new URL(
    "https://secure.staging.paypipes.net/api/v2/transaction"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json (or application/x-www-form-url-encoded)",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://secure.staging.paypipes.net/api/v2/transaction';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json (or application/x-www-form-url-encoded)',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://secure.staging.paypipes.net/api/v2/transaction'
headers = {
  'Authorization': 'Bearer {ACCESS_TOKEN}',
  'Content-Type': 'application/json (or application/x-www-form-url-encoded)'
}

response = requests.request('POST', url, headers=headers)
response.json()

Example response (200, Successful response):


[
    {
        "version": 2,
        "orderID": "ORD1234567890",
        "trxID": "6c37e2d5-92cc-4241-a9f8-9813720aec64",
        "trxType": "Purchase",
        "amount": "15.00",
        "currency": "EUR",
        "status": "Waiting",
        "paymentStatus": null,
        "statusCode": "200",
        "statusDescription": "",
        "declineCode": null,
        "created": "2024-06-04T10:50:38.000000Z",
        "cardToken": "E75C608271E3852BA81A87540085",
        "customerToken": "11cc649a-cdab-4b26-b9ec-781920174ca6",
        "description": "Charge transaction with ID #ORD1234567890",
        "gateway": "ecommpay",
        "applePay": false,
        "googlePay": false,
        "refNo": null,
        "requestID": "6c37e2d5-92cc-4241-a9f8-9813720aec6",
        "authCode": null,
        "card": {
            "holder": "John Doe",
            "bin": "401200",
            "digit": "0085",
            "brand": "visa",
            "cardLevel": "CLASSIC",
            "expired": "12/2025",
            "maskNumber": "4012 00XX XXXX 0085"
        },
        "bank": null,
        "customerBank": null,
        "fees": null,
        "meta": null
    },
    {
        "version": 2,
        "orderID": "ORD1234567890",
        "trxID": "6c37e2d5-92cc-4241-a9f8-9813720aec64",
        "trxType": "Purchase",
        "amount": "15.00",
        "currency": "EUR",
        "status": "Waiting",
        "paymentStatus": null,
        "statusCode": "200",
        "statusDescription": "",
        "declineCode": null,
        "created": "2024-06-04T10:50:38.000000Z",
        "cardToken": "E75C608271E3852BA81A87540085",
        "customerToken": "11cc649a-cdab-4b26-b9ec-781920174ca6",
        "description": "Charge transaction with ID #ORD1234567890",
        "gateway": "ecommpay",
        "applePay": false,
        "googlePay": false,
        "refNo": null,
        "requestID": "6c37e2d5-92cc-4241-a9f8-9813720aec6",
        "authCode": null,
        "card": {
            "holder": "John Doe",
            "bin": "401200",
            "digit": "0085",
            "brand": "visa",
            "cardLevel": "CLASSIC",
            "expired": "12/2025",
            "maskNumber": "4012 00XX XXXX 0085"
        },
        "bank": null,
        "customerBank": null,
        "fees": null,
        "meta": null
    }
]
 

Example response (400, Error response):


{
    "error": "Bad request",
    "code": 200000
}
 

Example response (401, Error response):


{
    "error": "Unauthenticated",
    "code": 100001
}
 

Example response (403, Error response):


{
    "error": "Unauthorized",
    "code": 100004
}
 

Example response (404, Error response):


{
    "error": "Record not found",
    "code": 200007
}
 

Example response (405, Error response):


{
    "error": "The specified method for the request is invalid",
    "code": 200008
}
 

Example response (410, Error response):


{
    "error": "Transaction has expired (Transaction ID: #ID)",
    "code": 200037
}
 

Example response (422, Error response):


{
    "error": "Transaction has invalid status: Pending",
    "code": 200013
}
 

Request      

POST api/v2/transaction

Headers

Authorization      

Example: Bearer {ACCESS_TOKEN}

Content-Type      

Example: application/json (or application/x-www-form-url-encoded)

Body Parameters

transaction_id   string  optional  

This field is required when none of order_id and purchase_request_id are present.

order_id   string  optional  

This field is required when none of transaction_id and purchase_request_id are present.

purchase_request_id   string  optional  

This field is required when none of transaction_id and order_id are present.

Response

Response Fields

Response 200      

Successful response

version   integer   

Indicates the version of the API. Example: 2

orderID   string   

Merchant's internal unique ID for the transaction. Example: ORD1234567890

trxID   string   

A unique identifier for the transaction. Example: 6c37e2d5-92cc-4241-a9f8-9813720aec64

trxType   string   

Specifies the type of the transaction. Allowed values: Purchase, Reverse, Refund. Example: Refund

amount   string   

The value representing the actual amount for the transaction. Format: DECIMAL(20,2) Example: 15.00

currency   string   

The currency code for the transaction, complies with the ISO 4217 standard. Example: EUR

status   string   

The current status of the transaction. Allowed values: Approved, Declined, Cancelled. Example: Approved

paymentStatus   string   

Additional status information regarding the payment, if available. Allowed values: Refunded, Partially refunded. Example: null

statusCode   string   

A code representing the detailed status of the transaction. Typically, this code is provided directly by the third-party gateway. In some instances, such as an internal error, an error code from our predefined list will be displayed. Example: 200

statusDescription   string   

A textual description of the status code. Example: Transaction has been refunded

declineCode   string   

Paypipes decline code. See Decline Codes table.

created   string   

The timestamp when the transaction was created. Example: 2024-06-04T10:50:38.000000Z

cardToken   string   

A token representing the customer's card information. Example: E75C608271E3852BA81A87540085

customerToken   string   

A token representing the customer. Example: 11cc649a-cdab-4b26-b9ec-781920174ca6

description   string   

A description of the transaction. Example: Refund transaction with ID #ORD1234567890

gateway   string   

The payment gateway used to process the transaction. Allowed values: Gateways Example: trustpay

applePay   boolean   

Indicates whether Apple Pay was used for the transaction. Example: false

googlePay   boolean   

Indicates whether Google Pay was used for the transaction. Example: false

refNo   string   

A reference number for the transaction, received from the third-party gateway. Example: null

requestID   string   

A unique identifier for the request associated with the transaction. This ID is sent to the third-party gateway. Example: 6c37e2d5-92cc-4241-a9f8-9813720aec6

authCode   string   

The authorization code for the transaction, if applicable. Example: null

card   Card   

Contains details about the card used for the transaction.

holder   string   

The name of the cardholder. Example: John Doe

bin   string   

The Bank Identification Number of the card. Example: 401200

digit   string   

The last four digits of the card number. Example: 0085

brand   string   

The brand of the card (e.g., Visa, Mastercard). Example: visa

cardLevel   string|null   

The level or type of the card. Example: CLASSIC

expired   string   

The expiration date of the card. Example: 12/2025

maskNumber   string   

The masked card number for security purposes. Example: 4012 00XX XXXX 0085

bank   Object   

Additional information about the bank account which was used for deposit. Example: null

customerBank   CustomerBank   

Contains detailed information about the customer's bank account.

bank_token   string   

A token identifying the bank account. Example: a6a6509b-26dc-49cc-b0e6-92c5d6eede36

customer_token   string   

A token identifying the customer who owns the bank account. Example: 496d8b1f-916e-4f79-bab6-a09a223ecffb

title   string   

The name of the bank account. Example: Bank Account

currency   string   

The currency code representing the currency in which the bank account is denominated. Example: USD

beneficiary_name   string   

The name of the account holder or the customer who owns the bank account. Example: John Doe

beneficiary_address   string   

The address of the account holder. Example: 123 Maple Street, London

bank_name   string   

The name of the bank where the customer's account is held. Example: Metro Bank

branch_name   string   

The name of the specific branch of the bank where the customer's account is maintained. Example: MetroBank

bank_address   string   

The address of the bank where the customer's account is held. Example: 123 Maple Street, London

bank_code   string   

The code that uniquely identifies the bank. Example: 0100

account_number   string   

The bank account number that uniquely identifies the customer's bank account. Example: 789456123

iban   string   

An international standard account number (IBAN) used to uniquely identify the customer's bank account for cross-border transactions. Example: GB23MBTC60161331926819

bic   string   

An international standard code (BIC/SWIFT) used to identify the customer's bank for cross-border transactions. Example: MBTCPHMMXXX

account_type   string   

The type of the bank account. Example: current

fees   Fee   

Contains details about any fees associated with the transaction. This object includes information such as the name, type, amount, and currency of the fee.

name   string   

The name of the fee. Example: Service Fee

type   string   

The type of the fee, indicating its purpose or category. Example: processing

amount   string   

The amount of the fee. Example: 50.00

currency   string   

The currency in which the fee amount is denominated. Example: USD

meta   Object   

Additional metadata related to the transaction, if available. Example: null

Response 400|401|403|404|405|410|422      

Error response

error   string   

This parameter contains a message describing the error that occurred. Example: Invalid currency

code   integer   

This parameter provides a numeric code that uniquely identifies the specific error. Example: 100003

Withdraw - Inpay

requires authentication

The withdraw endpoint creates a transaction using the customer token by sending a POST request over HTTPS to the /inpay/withdraw endpoint. This triggers the creation of a new transaction

Example request:
curl --request POST \
    "https://secure.staging.paypipes.net/api/v2/inpay/withdraw" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json (or application/x-www-form-url-encoded)" \
    --data "{
    \"customer_token\": \"99cc649a-cdab-4b26-b9ec-781920174ca6\",
    \"bank_token\": \"0402763a-1a10-47ae-b00a-95d773177aa3\",
    \"order_id\": \"ORD1234567890\",
    \"description\": \"Withdraw transaction with ID #ORD1234567890\",
    \"amount\": \"1000.00\",
    \"currency\": \"JPY\",
    \"callback_url\": \"https:\\/\\/example.com\\/callback\",
    \"creditor\": {
        \"name\": \"Jane Doe\",
        \"address_lines\": \"Schillerstrasse 78\",
        \"postcode\": \"120-0015\",
        \"city\": \"Scherstetten\",
        \"state\": \"Adachi\",
        \"country_code\": \"JP\",
        \"birthdate\": \"1959-09-01\"
    },
    \"creditor_account\": {
        \"account_number\": \"00012345\",
        \"country_code\": \"JP\",
        \"bank_name\": \"Test Bank\"
    }
}"
const url = new URL(
    "https://secure.staging.paypipes.net/api/v2/inpay/withdraw"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json (or application/x-www-form-url-encoded)",
    "Accept": "application/json",
};

let body = {
    "customer_token": "99cc649a-cdab-4b26-b9ec-781920174ca6",
    "bank_token": "0402763a-1a10-47ae-b00a-95d773177aa3",
    "order_id": "ORD1234567890",
    "description": "Withdraw transaction with ID #ORD1234567890",
    "amount": "1000.00",
    "currency": "JPY",
    "callback_url": "https:\/\/example.com\/callback",
    "creditor": {
        "name": "Jane Doe",
        "address_lines": "Schillerstrasse 78",
        "postcode": "120-0015",
        "city": "Scherstetten",
        "state": "Adachi",
        "country_code": "JP",
        "birthdate": "1959-09-01"
    },
    "creditor_account": {
        "account_number": "00012345",
        "country_code": "JP",
        "bank_name": "Test Bank"
    }
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://secure.staging.paypipes.net/api/v2/inpay/withdraw';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json (or application/x-www-form-url-encoded)',
        ],
        'json' => [
            'customer_token' => '99cc649a-cdab-4b26-b9ec-781920174ca6',
            'bank_token' => '0402763a-1a10-47ae-b00a-95d773177aa3',
            'order_id' => 'ORD1234567890',
            'description' => 'Withdraw transaction with ID #ORD1234567890',
            'amount' => '1000.00',
            'currency' => 'JPY',
            'callback_url' => 'https://example.com/callback',
            'creditor' => [
                'name' => 'Jane Doe',
                'address_lines' => 'Schillerstrasse 78',
                'postcode' => '120-0015',
                'city' => 'Scherstetten',
                'state' => 'Adachi',
                'country_code' => 'JP',
                'birthdate' => '1959-09-01',
            ],
            'creditor_account' => [
                'account_number' => '00012345',
                'country_code' => 'JP',
                'bank_name' => 'Test Bank',
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://secure.staging.paypipes.net/api/v2/inpay/withdraw'
payload = {
    "customer_token": "99cc649a-cdab-4b26-b9ec-781920174ca6",
    "bank_token": "0402763a-1a10-47ae-b00a-95d773177aa3",
    "order_id": "ORD1234567890",
    "description": "Withdraw transaction with ID #ORD1234567890",
    "amount": "1000.00",
    "currency": "JPY",
    "callback_url": "https:\/\/example.com\/callback",
    "creditor": {
        "name": "Jane Doe",
        "address_lines": "Schillerstrasse 78",
        "postcode": "120-0015",
        "city": "Scherstetten",
        "state": "Adachi",
        "country_code": "JP",
        "birthdate": "1959-09-01"
    },
    "creditor_account": {
        "account_number": "00012345",
        "country_code": "JP",
        "bank_name": "Test Bank"
    }
}
headers = {
  'Authorization': 'Bearer {ACCESS_TOKEN}',
  'Content-Type': 'application/json (or application/x-www-form-url-encoded)'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (200, Successful response):


{
    "version": 2,
    "orderID": "order123",
    "trxID": "54adcf49-b19f-4f84-a8a4-c7969cb50cb6",
    "trxType": "Withdraw",
    "amount": "1.00",
    "currency": "EUR",
    "status": "Waiting",
    "paymentStatus": null,
    "statusCode": "0",
    "statusDescription": "received",
    "declineCode": null,
    "created": "2024-10-08T10:46:16.000000Z",
    "cardToken": null,
    "customerToken": "5712cd65-78bb-43f8-9b9a-a8fa4ac43c18",
    "description": "Test withdrawal",
    "gateway": "inpay",
    "applePay": false,
    "googlePay": false,
    "refNo": "4CRK4Q9",
    "requestID": "54adcf49-b19f-4f84-a8a4-c7969cb50cb6",
    "authCode": null,
    "card": null,
    "bank": null,
    "customerBank": null,
    "fees": null,
    "meta": null
}
 

Example response (400, Error response):


{
    "error": "Bad request",
    "code": 200000
}
 

Example response (401, Error response):


{
    "error": "Unauthenticated",
    "code": 100001
}
 

Example response (403, Error response):


{
    "error": "Unauthorized",
    "code": 100004
}
 

Example response (404, Error response):


{
    "error": "Record not found",
    "code": 200007
}
 

Example response (405, Error response):


{
    "error": "The specified method for the request is invalid",
    "code": 200008
}
 

Example response (422, Error response):


{
    "error": "Invalid currency",
    "code": 100003
}
 

Request      

POST api/v2/inpay/withdraw

Headers

Authorization      

Example: Bearer {ACCESS_TOKEN}

Content-Type      

Example: application/json (or application/x-www-form-url-encoded)

Body Parameters

customer_token   string   

A token identifying the customer. This field is required when card_token is not present. Example: 99cc649a-cdab-4b26-b9ec-781920174ca6

bank_token   string   

A token identifying the bank of the customer used for the transaction. The bank_token of an existing record in the customer_banks table. Example: 0402763a-1a10-47ae-b00a-95d773177aa3

order_id   string  optional  

Merchant's internal unique ID for the transaction. Must not be greater than 40 characters. Must be at least 1 character. Example: ORD1234567890

description   string   

Description of the transaction. Must not be greater than 255 characters. Must be at least 5 characters. Example: Withdraw transaction with ID #ORD1234567890

amount   string   

The value representing the actual amount for the transaction. The decimal points must match the currency's decimal point length. For example, for USD currency, valid amounts include "5.99", "6.00", or "6". An amount like "5.995" would throw a validation error due to an invalid amount specified. Must not be greater than 10 characters. Example: 1000.00

currency   string   

The currency code for the transaction, which must comply with the ISO 4217 standard and be represented by a three-letter code. The cy_code of an existing record in the currencies table. Example: JPY

callback_url   string  optional  

URL used to receive callback notification with information about the transaction. Must be a valid URL. Must not be greater than 255 characters. Example: https://example.com/callback

creditor   object   

Creditor details including name, address, and identification.

name   string   

The name of the creditor. Example: Jane Doe

address_lines   string   

The address lines of the creditor. Example: Schillerstrasse 78

postcode   string   

The postcode of the creditor. Example: 120-0015

city   string   

The city of the creditor. Example: Scherstetten

state   string   

The state of the creditor. Example: Adachi

country_code   string   

The ISO country code of the creditor. Must be 2 characters. Example: JP

birthdate   string   

The birthdate of the creditor in YYYY-MM-DD format. Must be a valid date. Example: 1959-09-01

creditor_account   object   

Creditor account details.

account_number   string   

The account number/iban of the creditor. Example: 00012345

country_code   string   

The ISO country code of the creditor's bank. Must be 2 characters. Example: JP

bank_name   string   

The name of the creditor's bank.This field is only required for JPY transactions. Example: Test Bank

Response

Response Fields

Response 200      

Successful response

version   integer   

Indicates the version of the API. Example: 2

orderID   string   

Merchant's internal unique ID for the transaction. Example: ORD1234567890

trxID   string   

A unique identifier for the transaction. Example: 6c37e2d5-92cc-4241-a9f8-9813720aec64

trxType   string   

Specifies the type of the transaction. Allowed values: Purchase, Reverse, Refund, Withdraw. Example: Withdraw

amount   string   

The value representing the actual amount for the transaction. Format: DECIMAL(20,2) Example: 15.00

currency   string   

The currency code for the transaction, complies with the ISO 4217 standard. Example: EUR

status   string   

The current status of the transaction. Allowed values: Approved, Declined, Cancelled. Example: Approved

paymentStatus   string   

Additional status information regarding the payment, if available. Allowed values: Refunded, Partially refunded. Example: null

statusCode   string   

A code representing the detailed status of the transaction. Typically, this code is provided directly by the third-party gateway. In some instances, such as an internal error, an error code from our predefined list will be displayed. Example: 200

statusDescription   string   

A textual description of the status code. Example: Withdraw request created

declineCode   string   

Paypipes decline code. See Decline Codes table.

created   string   

The timestamp when the transaction was created. Example: 2024-06-04T10:50:38.000000Z

cardToken   string   

A token representing the customer's card information. Example: E75C608271E3852BA81A87540085

customerToken   string   

A token representing the customer. Example: 11cc649a-cdab-4b26-b9ec-781920174ca6

description   string   

A description of the transaction. Example: Withdraw transaction with ID #ORD1234567890

gateway   string   

The payment gateway used to process the transaction. Allowed values: Gateways Example: inpay

applePay   boolean   

Indicates whether Apple Pay was used for the transaction. Example: false

googlePay   boolean   

Indicates whether Google Pay was used for the transaction. Example: false

refNo   string   

A reference number for the transaction, received from the third-party gateway. Example: null

requestID   string   

A unique identifier for the request associated with the transaction. This ID is sent to the third-party gateway. Example: 6c37e2d5-92cc-4241-a9f8-9813720aec6

authCode   string   

The authorization code for the transaction, if applicable. Example: null

card   Card   

Contains details about the card used for the transaction.

holder   string   

The name of the cardholder. Example: John Doe

bin   string   

The Bank Identification Number of the card. Example: 401200

digit   string   

The last four digits of the card number. Example: 0085

brand   string   

The brand of the card (e.g., Visa, Mastercard). Example: visa

cardLevel   string   

The level or type of the card. Example: CLASSIC

expired   string   

The expiration date of the card. Example: 12/2025

maskNumber   string   

The masked card number for security purposes. Example: 4012 00XX XXXX 0085

bank   Object   

Additional information about the bank account which was used for deposit. Example: null

customerBank   CustomerBank   

Contains detailed information about the customer's bank account.

bank_token   string   

A token identifying the bank account. Example: a6a6509b-26dc-49cc-b0e6-92c5d6eede36

customer_token   string   

A token identifying the customer who owns the bank account. Example: 496d8b1f-916e-4f79-bab6-a09a223ecffb

title   string   

The name of the bank account. Example: Bank Account

currency   string   

The currency code representing the currency in which the bank account is denominated. Example: USD

beneficiary_name   string   

The name of the account holder or the customer who owns the bank account. Example: John Doe

beneficiary_address   string   

The address of the account holder. Example: 123 Maple Street, London

bank_name   string   

The name of the bank where the customer's account is held. Example: Metro Bank

branch_name   string   

The name of the specific branch of the bank where the customer's account is maintained. Example: MetroBank

bank_address   string   

The address of the bank where the customer's account is held. Example: 123 Maple Street, London

bank_code   string   

The code that uniquely identifies the bank. Example: 0100

account_number   string   

The bank account number that uniquely identifies the customer's bank account. Example: 789456123

iban   string   

An international standard account number (IBAN) used to uniquely identify the customer's bank account for cross-border transactions. Example: GB23MBTC60161331926819

bic   string   

An international standard code (BIC/SWIFT) used to identify the customer's bank for cross-border transactions. Example: MBTCPHMMXXX

account_type   string   

The type of the bank account. Example: current

bank_clearing_system_code   string   

The bank clearing code (ISO 20022). Example: SGIBG

bank_clearing_system_id   string   

The bank clearing identifier (ISO 20022). Example: 1234567

fees   Fee   

Contains details about any fees associated with the transaction. This object includes information such as the name, type, amount, and currency of the fee.

name   string   

The name of the fee. Example: Service Fee

type   string   

The type of the fee, indicating its purpose or category. Example: processing

amount   string   

The amount of the fee. Example: 50.00

currency   string   

The currency in which the fee amount is denominated. Example: USD

meta   Object   

Additional metadata related to the transaction, if available. Example: null

Response 400|401|403|404|405|410|422      

Error response

error   string   

This parameter contains a message describing the error that occurred. Example: Invalid currency

code   integer   

This parameter provides a numeric code that uniquely identifies the specific error. Example: 100003

Status

requires authentication

To get information about the current status of a transaction, call the status endpoint with the transaction_id.

Example request:
curl --request GET \
    --get "https://secure.staging.paypipes.net/api/v2/transaction/b748bab7-e930-42f4-b673-fe29e30acad3" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json (or application/x-www-form-url-encoded)"
const url = new URL(
    "https://secure.staging.paypipes.net/api/v2/transaction/b748bab7-e930-42f4-b673-fe29e30acad3"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json (or application/x-www-form-url-encoded)",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://secure.staging.paypipes.net/api/v2/transaction/b748bab7-e930-42f4-b673-fe29e30acad3';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json (or application/x-www-form-url-encoded)',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://secure.staging.paypipes.net/api/v2/transaction/b748bab7-e930-42f4-b673-fe29e30acad3'
headers = {
  'Authorization': 'Bearer {ACCESS_TOKEN}',
  'Content-Type': 'application/json (or application/x-www-form-url-encoded)'
}

response = requests.request('GET', url, headers=headers)
response.json()

Example response (200, Successful response):


{
    "version": 2,
    "orderID": "2381cfcc-e15d-4342-a5ef-5f758265f010",
    "trxID": "b748bab7-e930-42f4-b673-fe29e30acadc",
    "trxType": "Purchase",
    "amount": "15.00",
    "currency": "EUR",
    "status": "Pending",
    "paymentStatus": null,
    "statusCode": "",
    "statusDescription": null,
    "declineCode": null,
    "created": "2024-06-04T13:59:55.000000Z",
    "cardToken": null,
    "customerToken": "11cc649a-cdab-4b26-b9ec-781920174ca6",
    "description": "EUR test",
    "gateway": "trustpay",
    "applePay": false,
    "googlePay": false,
    "refNo": null,
    "requestID": null,
    "authCode": null,
    "card": null,
    "bank": null,
    "customerBank": null,
    "fees": null,
    "meta": null
}
 

Example response (400, Error response):


{
    "error": "Bad request",
    "code": 200000
}
 

Example response (401, Error response):


{
    "error": "Unauthenticated",
    "code": 100001
}
 

Example response (403, Error response):


{
    "error": "Unauthorized",
    "code": 100004
}
 

Example response (404, Error response):


{
    "error": "Record not found",
    "code": 200007
}
 

Example response (405, Error response):


{
    "error": "The specified method for the request is invalid",
    "code": 200008
}
 

Example response (410, Error response):


{
    "error": "Transaction has expired (Transaction ID: #ID)",
    "code": 200037
}
 

Example response (422, Error response):


{
    "error": "Invalid currency",
    "code": 100003
}
 

Request      

GET api/v2/transaction/{transaction_id}

Headers

Authorization      

Example: Bearer {ACCESS_TOKEN}

Content-Type      

Example: application/json (or application/x-www-form-url-encoded)

URL Parameters

transaction_id   string   

ID of the transaction. Example: b748bab7-e930-42f4-b673-fe29e30acad3

Response

Response Fields

Response 200      

Successful response

version   integer   

Indicates the version of the API. Example: 2

orderID   string   

Merchant's internal unique ID for the transaction. Example: 2381cfcc-e15d-4342-a5ef-5f758265f010

trxID   string   

A unique identifier for the transaction. Example: b748bab7-e930-42f4-b673-fe29e30acadc

trxType   string   

Specifies the type of the transaction. Allowed values: Purchase, Reverse, Refund. Example: Purchase

amount   string   

The value representing the actual amount for the transaction. Format: DECIMAL(20,2) Example: 15.00

currency   string   

The currency code for the transaction, complies with the ISO 4217 standard. Example: EUR

status   string   

The current status of the transaction. Allowed values: Approved, Declined, Cancelled. Example: Pending

paymentStatus   string   

Additional status information regarding the payment, if available. Allowed values: Refunded, Partially refunded. Example: null

statusCode   string   

A code representing the detailed status of the transaction. Typically, this code is provided directly by the third-party gateway. In some instances, such as an internal error, an error code from our predefined list will be displayed. Example: 200

statusDescription   string   

A textual description of the status code. Example: EUR test

declineCode   string   

Paypipes decline code. See Decline Codes table.

created   string   

The timestamp when the transaction was created. Example: 2024-06-04T10:50:38.000000Z

cardToken   string   

A token representing the customer's card information. Example: E75C608271E3852BA81A87540085

customerToken   string   

A token representing the customer. Example: 11cc649a-cdab-4b26-b9ec-781920174ca6

description   string   

A description of the transaction. Example: Reverse transaction with ID #ORD1234567890

gateway   string   

The payment gateway used to process the transaction. Allowed values: Gateways Example: trustpay

applePay   boolean   

Indicates whether Apple Pay was used for the transaction. Example: false

googlePay   boolean   

Indicates whether Google Pay was used for the transaction. Example: false

refNo   string   

A reference number for the transaction, received from the third-party gateway. Example: null

requestID   string   

A unique identifier for the request associated with the transaction. This ID is sent to the third-party gateway. Example: 6c37e2d5-92cc-4241-a9f8-9813720aec6

authCode   string   

The authorization code for the transaction, if applicable. Example: null

card   Card   

Contains details about the card used for the transaction.

holder   string   

The name of the cardholder. Example: John Doe

bin   string   

The Bank Identification Number of the card. Example: 401200

digit   string   

The last four digits of the card number. Example: 0085

brand   string   

The brand of the card (e.g., Visa, Mastercard). Example: visa

cardLevel   string   

The level or type of the card. Example: CLASSIC

expired   string   

The expiration date of the card. Example: 12/2025

maskNumber   string   

The masked card number for security purposes. Example: 4012 00XX XXXX 0085

bank   Object   

Additional information about the bank account which was used for deposit. Example: null

customerBank   CustomerBank   

Contains detailed information about the customer's bank account.

bank_token   string   

A token identifying the bank account. Example: a6a6509b-26dc-49cc-b0e6-92c5d6eede36

customer_token   string   

A token identifying the customer who owns the bank account. Example: 496d8b1f-916e-4f79-bab6-a09a223ecffb

title   string   

The name of the bank account. Example: Bank Account

currency   string   

The currency code representing the currency in which the bank account is denominated. Example: USD

beneficiary_name   string   

The name of the account holder or the customer who owns the bank account. Example: John Doe

beneficiary_address   string   

The address of the account holder. Example: 123 Maple Street, London

bank_name   string   

The name of the bank where the customer's account is held. Example: Metro Bank

branch_name   string   

The name of the specific branch of the bank where the customer's account is maintained. Example: MetroBank

bank_address   string   

The address of the bank where the customer's account is held. Example: 123 Maple Street, London

bank_code   string   

The code that uniquely identifies the bank. Example: 0100

account_number   string   

The bank account number that uniquely identifies the customer's bank account. Example: 789456123

iban   string   

An international standard account number (IBAN) used to uniquely identify the customer's bank account for cross-border transactions. Example: GB23MBTC60161331926819

bic   string   

An international standard code (BIC/SWIFT) used to identify the customer's bank for cross-border transactions. Example: MBTCPHMMXXX

account_type   string   

The type of the bank account. Example: current

bank_clearing_system_code   string   

The bank clearing code (ISO 20022). Example: SGIBG

bank_clearing_system_id   string   

The bank clearing identifier (ISO 20022). Example: 1234567

fees   Fee   

Contains details about any fees associated with the transaction. This object includes information such as the name, type, amount, and currency of the fee.

name   string   

The name of the fee. Example: Service Fee

type   string   

The type of the fee, indicating its purpose or category. Example: processing

amount   string   

The amount of the fee. Example: 50.00

currency   string   

The currency in which the fee amount is denominated. Example: USD

meta   Object   

Additional metadata related to the transaction, if available. Example: null

Response 400|401|403|404|405|410|422      

Error response.

error   string   

This parameter contains a message describing the error that occurred. Example: Invalid currency

code   int   

This parameter provides a numeric code that uniquely identifies the specific error. Example: 100003

Customer

Create

requires authentication

A tokenize customer request transforms user data into a token and must be performed before a purchase. This request is sent by making a POST request over HTTPS to the /tokenize/customers endpoint.

Example request:
curl --request POST \
    "https://secure.staging.paypipes.net/api/v2/tokenize/customers" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json (or application/x-www-form-url-encoded)" \
    --data "{
    \"first_name\": \"John\",
    \"last_name\": \"Doe\",
    \"jp_fullname\": \"ε±±η”° ε€ͺιƒŽ\",
    \"street\": \"123 Maple Street\",
    \"city\": \"London\",
    \"state\": \"CA\",
    \"post_code\": \"94107\",
    \"country\": \"GB\",
    \"email\": \"john.doe@example.com\",
    \"phone_code\": \"+44\",
    \"phone\": \"5551234567\",
    \"reference_id\": \"ABC123XYZ\",
    \"date_of_birth\": \"2021-10-20\",
    \"legal_entity\": \"PRIVATE\",
    \"identifiers\": [
        {
            \"id\": \"123456\",
            \"gateway\": \"trustpay\"
        },
        {
            \"id\": \"456789\",
            \"gateway\": \"unlimit\"
        }
    ]
}"
const url = new URL(
    "https://secure.staging.paypipes.net/api/v2/tokenize/customers"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json (or application/x-www-form-url-encoded)",
    "Accept": "application/json",
};

let body = {
    "first_name": "John",
    "last_name": "Doe",
    "jp_fullname": "ε±±η”° ε€ͺιƒŽ",
    "street": "123 Maple Street",
    "city": "London",
    "state": "CA",
    "post_code": "94107",
    "country": "GB",
    "email": "john.doe@example.com",
    "phone_code": "+44",
    "phone": "5551234567",
    "reference_id": "ABC123XYZ",
    "date_of_birth": "2021-10-20",
    "legal_entity": "PRIVATE",
    "identifiers": [
        {
            "id": "123456",
            "gateway": "trustpay"
        },
        {
            "id": "456789",
            "gateway": "unlimit"
        }
    ]
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://secure.staging.paypipes.net/api/v2/tokenize/customers';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json (or application/x-www-form-url-encoded)',
        ],
        'json' => [
            'first_name' => 'John',
            'last_name' => 'Doe',
            'jp_fullname' => 'ε±±η”° ε€ͺιƒŽ',
            'street' => '123 Maple Street',
            'city' => 'London',
            'state' => 'CA',
            'post_code' => '94107',
            'country' => 'GB',
            'email' => 'john.doe@example.com',
            'phone_code' => '+44',
            'phone' => '5551234567',
            'reference_id' => 'ABC123XYZ',
            'date_of_birth' => '2021-10-20',
            'legal_entity' => 'PRIVATE',
            'identifiers' => [
                [
                    'id' => '123456',
                    'gateway' => 'trustpay',
                ],
                [
                    'id' => '456789',
                    'gateway' => 'unlimit',
                ],
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://secure.staging.paypipes.net/api/v2/tokenize/customers'
payload = {
    "first_name": "John",
    "last_name": "Doe",
    "jp_fullname": "ε±±η”° ε€ͺιƒŽ",
    "street": "123 Maple Street",
    "city": "London",
    "state": "CA",
    "post_code": "94107",
    "country": "GB",
    "email": "john.doe@example.com",
    "phone_code": "+44",
    "phone": "5551234567",
    "reference_id": "ABC123XYZ",
    "date_of_birth": "2021-10-20",
    "legal_entity": "PRIVATE",
    "identifiers": [
        {
            "id": "123456",
            "gateway": "trustpay"
        },
        {
            "id": "456789",
            "gateway": "unlimit"
        }
    ]
}
headers = {
  'Authorization': 'Bearer {ACCESS_TOKEN}',
  'Content-Type': 'application/json (or application/x-www-form-url-encoded)'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (201, Successful response):


{
    "customer_token": "496d8b1f-916e-4f79-bab6-a09a223ecffb",
    "first_name": "John",
    "last_name": "Doe",
    "jp_fullname": "ε±±η”° ε€ͺιƒŽ",
    "street": "123 Maple Street",
    "city": "London",
    "state": null,
    "post_code": "94107",
    "country": "GB",
    "phone_code": "+44",
    "phone": "5551234567",
    "email": "john.doe@example.com",
    "reference_id": "ABC123XYZ",
    "date_of_birth": "2021-10-20",
    "legal_entity": "PRIVATE",
    "status": "Active",
    "created": "2024-06-04T10:06:57.000000Z",
    "updated": "2024-06-04T10:06:57.000000Z",
    "identifiers": [
        {
            "id": "123456",
            "gateway": "trustpay",
            "created": "2024-06-04T10:06:57.000000Z",
            "updated": "2024-06-04T10:06:57.000000Z"
        },
        {
            "id": "456789",
            "gateway": "unlimit",
            "created": "2024-06-04T10:06:57.000000Z",
            "updated": "2024-06-04T10:06:57.000000Z"
        }
    ],
    "banks": [
        {
            "bank_token": "c9c97d4a-d1c3-4aa4-abd2-a32436800437",
            "customer_token": "496d8b1f-916e-4f79-bab6-a09a223ecffb",
            "title": "Test bank account",
            "currency": "JPY",
            "beneficiary_name": "John Doe",
            "beneficiary_address": "123 Maple Street, London",
            "bank_name": "Metro Bank",
            "branch_name": "MetroBank",
            "bank_address": "123 Maple Street, London",
            "bank_code": "0100",
            "account_number": "1234567890",
            "iban": "GB23MBTC60161331926819",
            "bic": "MBTCPHMMXXX",
            "account_type": "checking",
            "bank_clearing_system_code": "SGIBG",
            "bank_clearing_system_id": "1234567"
        }
    ]
}
 

Example response (400, Error response):


{
    "error": "Bad request",
    "code": 200000
}
 

Example response (401, Error response):


{
    "error": "Unauthenticated",
    "code": 100001
}
 

Example response (403, Error response):


{
    "error": "Unauthorized",
    "code": 100004
}
 

Example response (404, Error response):


{
    "error": "Record not found",
    "code": 200007
}
 

Example response (405, Error response):


{
    "error": "The specified method for the request is invalid",
    "code": 200008
}
 

Example response (410, Error response):


{
    "error": "Transaction has expired (Transaction ID: #ID)",
    "code": 200037
}
 

Example response (422, Error response):


{
    "error": "Invalid currency",
    "code": 100003
}
 

Request      

POST api/v2/tokenize/customers

Headers

Authorization      

Example: Bearer {ACCESS_TOKEN}

Content-Type      

Example: application/json (or application/x-www-form-url-encoded)

Body Parameters

first_name   string   

The first name of the customer. Must not be greater than 60 characters. Example: John

last_name   string   

The last name of the customer. Must not be greater than 60 characters. Example: Doe

jp_fullname   string  optional  

The full name in Japanese. Must not be greater than 120 characters. Example: ε±±η”° ε€ͺιƒŽ

street   string  optional  

The street address. Must not be greater than 100 characters. Example: 123 Maple Street

city   string  optional  

The city of the address. Must be at least 2 characters. Must not be greater than 40 characters. Example: London

state   string  optional  

The state of the address. Must be at least 2 characters. Must not be greater than 40 characters. Example: CA

post_code   string  optional  

The postal code of the address. Must be at least 2 characters. Must not be greater than 20 characters. Example: 94107

country   string  optional  

The country code of the address. Must be a valid ISO 3166-1 alpha-2 country code. The country_code of an existing record in the countries table. Must be 2 characters. Example: GB

email   string   

The email address of the customer. Must be a valid email address. Must not be greater than 100 characters. Example: john.doe@example.com

phone_code   string  optional  

The international phone code. Must match the regex /^+?\d{1,4}$/. Example: +44

phone   string  optional  

The phone number. Must match the regex /^+?\d[\d-]*$/. Must be at least 5 characters. Must not be greater than 20 characters. Example: 5551234567

reference_id   string  optional  

A customer's unique identifier. Must be at least 1 character. Must not be greater than 64 characters. Example: ABC123XYZ

date_of_birth   string  optional  

The date of birth. Must be a valid date in the format Y-m-d. Example: 2021-10-20

legal_entity   string  optional  

The legal status of the customer (PRIVATE/BUSINESS). Example: PRIVATE

Must be one of:
  • PRIVATE
  • BUSINESS
identifiers   object[]  optional  

An array of customer's unique identifiers belonging to specific gateways. Each object in the array must contain a numeric id, which represents the unique identifier, and a string gateway, which represents the name of the gateway.

id   string  optional  

The unique identifier. Example: 123456

gateway   string  optional  

The name of the gateway. Example: trustpay

Response

Response Fields

Response 201      

Successful response

customer_token   string   

A token identifying the customer. Example: 496d8b1f-916e-4f79-bab6-a09a223ecffb

first_name   string   

The first name of the customer. Example: John

last_name   string   

The last name of the customer. Example: Doe

jp_fullname   string   

The full name in Japanese. Example: ε±±η”° ε€ͺιƒŽ

street   string   

The street address. Example: 123 Maple Street

city   string   

The city of the address. Example: London

state   string   

The state of the address. Example: null

post_code   string   

The postal code of the address. Example: 94107

country   string   

The country code of the address. Example: GB

phone_code   string   

The international phone code. Example: +44

phone   string   

The phone number. Example: 5551234567

email   string   

The email address of the customer. Example: john.doe@example.com

reference_id   string   

A customer's unique identifier. Example: ABC123XYZ

date_of_birth   date   

The date of birth. Example: 2021-10-20

legal_entity   string   

The legal status of the customer (PRIVATE/BUSINESS). Example: PRIVATE

status   string   

This parameter indicates the current status of the customer within the system. Possible values: Active, Inactive. Example: Active

created   string   

This parameter indicates the date and time when the customer's record was initially created in the system. Example: 2024-06-04T10:06:57.000000Z

updated   string   

This parameter indicates the most recent date and time when the customer's record was updated. Example: 2024-06-04T10:06:57.000000Z

identifiers   object[]   

An array of customer's unique identifiers belonging to specific gateways. Each object in the array must contain a numeric id, which represents the unique identifier, and a string gateway, which represents the name of the gateway.

id   string   

The unique identifier. Example: 123456

gateway   string   

The name of the gateway. Example: trustpay

banks   object[]   

An array of customer's banks.

bank_token   string   

A token identifying the bank account. Example: a6a6509b-26dc-49cc-b0e6-92c5d6eede36

customer_token   string   

A token identifying the customer who owns the bank account. Example: 496d8b1f-916e-4f79-bab6-a09a223ecffb

title   string   

The name of the bank account. Example: Bank Account

currency   string   

The currency code representing the currency in which the bank account is denominated. Example: USD

beneficiary_name   string   

The name of the account holder or the customer who owns the bank account. Example: John Doe

beneficiary_address   string   

The address of the account holder. Example: 123 Maple Street, London

bank_name   string   

The name of the bank where the customer's account is held. Example: Metro Bank

branch_name   string   

The name of the specific branch of the bank where the customer's account is maintained. Example: MetroBank

bank_address   string   

The address of the bank where the customer's account is held. Example: 123 Maple Street, London

bank_code   string   

The code that uniquely identifies the bank. Example: 0100

account_number   string   

The bank account number that uniquely identifies the customer's bank account. Example: 789456123

iban   string   

An international standard account number (IBAN) used to uniquely identify the customer's bank account for cross-border transactions. Example: GB23MBTC60161331926819

bic   string   

An international standard code (BIC/SWIFT) used to identify the customer's bank for cross-border transactions. Example: MBTCPHMMXXX

account_type   string   

The type of the bank account. Example: current

bank_clearing_system_code   string   

The bank clearing code (ISO 20022). Example: SGIBG

bank_clearing_system_id   string   

The bank clearing identifier (ISO 20022). Example: 1234567

Response 400|401|403|404|405|410|422      

Error response

error   string   

This parameter contains a message describing the error that occurred. Example: Invalid currency

code   integer   

This parameter provides a numeric code that uniquely identifies the specific error. Example: 100003

Update

requires authentication

You can update a tokenized customer with personal data by sending a PATCH request over HTTPS to the /tokenize/customers/{customer_token} endpoint.

Example request:
curl --request PATCH \
    "https://secure.staging.paypipes.net/api/v2/tokenize/customers/31e80148-746c-11e8-ad82-000d3a2b9844" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json (or application/x-www-form-url-encoded)" \
    --data "{
    \"first_name\": \"John\",
    \"last_name\": \"Doe\",
    \"jp_fullname\": \"ε±±η”° ε€ͺιƒŽ\",
    \"street\": \"123 Maple Street\",
    \"city\": \"London\",
    \"state\": \"CA\",
    \"post_code\": \"94107\",
    \"country\": \"GB\",
    \"email\": \"john.doe@example.com\",
    \"phone_code\": \"+44\",
    \"phone\": \"5551234567\",
    \"reference_id\": \"ABC123XYZ\",
    \"date_of_birth\": \"2021-10-20\",
    \"legal_entity\": \"PRIVATE\",
    \"identifiers\": [
        {
            \"id\": \"123456\",
            \"gateway\": \"trustpay\"
        },
        {
            \"id\": \"456789\",
            \"gateway\": \"unlimit\"
        }
    ]
}"
const url = new URL(
    "https://secure.staging.paypipes.net/api/v2/tokenize/customers/31e80148-746c-11e8-ad82-000d3a2b9844"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json (or application/x-www-form-url-encoded)",
    "Accept": "application/json",
};

let body = {
    "first_name": "John",
    "last_name": "Doe",
    "jp_fullname": "ε±±η”° ε€ͺιƒŽ",
    "street": "123 Maple Street",
    "city": "London",
    "state": "CA",
    "post_code": "94107",
    "country": "GB",
    "email": "john.doe@example.com",
    "phone_code": "+44",
    "phone": "5551234567",
    "reference_id": "ABC123XYZ",
    "date_of_birth": "2021-10-20",
    "legal_entity": "PRIVATE",
    "identifiers": [
        {
            "id": "123456",
            "gateway": "trustpay"
        },
        {
            "id": "456789",
            "gateway": "unlimit"
        }
    ]
};

fetch(url, {
    method: "PATCH",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://secure.staging.paypipes.net/api/v2/tokenize/customers/31e80148-746c-11e8-ad82-000d3a2b9844';
$response = $client->patch(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json (or application/x-www-form-url-encoded)',
        ],
        'json' => [
            'first_name' => 'John',
            'last_name' => 'Doe',
            'jp_fullname' => 'ε±±η”° ε€ͺιƒŽ',
            'street' => '123 Maple Street',
            'city' => 'London',
            'state' => 'CA',
            'post_code' => '94107',
            'country' => 'GB',
            'email' => 'john.doe@example.com',
            'phone_code' => '+44',
            'phone' => '5551234567',
            'reference_id' => 'ABC123XYZ',
            'date_of_birth' => '2021-10-20',
            'legal_entity' => 'PRIVATE',
            'identifiers' => [
                [
                    'id' => '123456',
                    'gateway' => 'trustpay',
                ],
                [
                    'id' => '456789',
                    'gateway' => 'unlimit',
                ],
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://secure.staging.paypipes.net/api/v2/tokenize/customers/31e80148-746c-11e8-ad82-000d3a2b9844'
payload = {
    "first_name": "John",
    "last_name": "Doe",
    "jp_fullname": "ε±±η”° ε€ͺιƒŽ",
    "street": "123 Maple Street",
    "city": "London",
    "state": "CA",
    "post_code": "94107",
    "country": "GB",
    "email": "john.doe@example.com",
    "phone_code": "+44",
    "phone": "5551234567",
    "reference_id": "ABC123XYZ",
    "date_of_birth": "2021-10-20",
    "legal_entity": "PRIVATE",
    "identifiers": [
        {
            "id": "123456",
            "gateway": "trustpay"
        },
        {
            "id": "456789",
            "gateway": "unlimit"
        }
    ]
}
headers = {
  'Authorization': 'Bearer {ACCESS_TOKEN}',
  'Content-Type': 'application/json (or application/x-www-form-url-encoded)'
}

response = requests.request('PATCH', url, headers=headers, json=payload)
response.json()

Example response (200, Successful response):


{
    "customer_token": "496d8b1f-916e-4f79-bab6-a09a223ecffb",
    "first_name": "John",
    "last_name": "Doe",
    "jp_fullname": "ε±±η”° ε€ͺιƒŽ",
    "street": "123 Maple Street",
    "city": "London",
    "state": null,
    "post_code": "94107",
    "country": "GB",
    "phone_code": "+44",
    "phone": "5551234567",
    "email": "john.doe@example.com",
    "reference_id": "ABC123XYZ",
    "date_of_birth": "2021-10-20",
    "legal_entity": "PRIVATE",
    "status": "Active",
    "created": "2024-06-04T10:06:57.000000Z",
    "updated": "2024-06-04T10:06:57.000000Z",
    "identifiers": [
        {
            "id": "123456",
            "gateway": "trustpay",
            "created": "2024-06-04T10:06:57.000000Z",
            "updated": "2024-06-04T10:06:57.000000Z"
        },
        {
            "id": "456789",
            "gateway": "unlimit",
            "created": "2024-06-04T10:06:57.000000Z",
            "updated": "2024-06-04T10:06:57.000000Z"
        }
    ],
    "banks": [
        {
            "bank_token": "c9c97d4a-d1c3-4aa4-abd2-a32436800437",
            "customer_token": "496d8b1f-916e-4f79-bab6-a09a223ecffb",
            "title": "Test bank account",
            "currency": "JPY",
            "beneficiary_name": "John Doe",
            "beneficiary_address": "123 Maple Street, London",
            "bank_name": "Metro Bank",
            "branch_name": "MetroBank",
            "bank_address": "123 Maple Street, London",
            "bank_code": "0100",
            "account_number": "1234567890",
            "iban": "GB23MBTC60161331926819",
            "bic": "MBTCPHMMXXX",
            "account_type": "checking",
            "bank_clearing_system_code": "SGIBG",
            "bank_clearing_system_id": "1234567"
        }
    ]
}
 

Example response (400, Error response):


{
    "error": "Bad request",
    "code": 200000
}
 

Example response (401, Error response):


{
    "error": "Unauthenticated",
    "code": 100001
}
 

Example response (403, Error response):


{
    "error": "Unauthorized",
    "code": 100004
}
 

Example response (404, Error response):


{
    "error": "Record not found",
    "code": 200007
}
 

Example response (405, Error response):


{
    "error": "The specified method for the request is invalid",
    "code": 200008
}
 

Example response (410, Error response):


{
    "error": "Transaction has expired (Transaction ID: #ID)",
    "code": 200037
}
 

Example response (422, Error response):


{
    "error": "Invalid currency",
    "code": 100003
}
 

Request      

PATCH api/v2/tokenize/customers/{customer_token}

Headers

Authorization      

Example: Bearer {ACCESS_TOKEN}

Content-Type      

Example: application/json (or application/x-www-form-url-encoded)

URL Parameters

customer_token   string   

Customer token of the existing customer. Example: 31e80148-746c-11e8-ad82-000d3a2b9844

Body Parameters

first_name   string  optional  

The first name of the customer. Must not be greater than 60 characters. Example: John

last_name   string  optional  

The last name of the customer. Must not be greater than 60 characters. Example: Doe

jp_fullname   string  optional  

The full name in Japanese. Must be at least 1 character. Must not be greater than 120 characters. Example: ε±±η”° ε€ͺιƒŽ

street   string  optional  

The street address. Must not be greater than 100 characters. Example: 123 Maple Street

city   string  optional  

The city of the address. Must be at least 2 characters. Must not be greater than 40 characters. Example: London

state   string  optional  

The state of the address. Must be at least 2 characters. Must not be greater than 40 characters. Example: CA

post_code   string  optional  

The postal code of the address. Must be at least 2 characters. Must not be greater than 20 characters. Example: 94107

country   string  optional  

The country code of the address. Must be a valid ISO 3166-1 alpha-2 country code. The country_code of an existing record in the countries table. Must be 2 characters. Example: GB

email   string  optional  

The email address of the customer. Must be a valid email address. Must not be greater than 100 characters. Example: john.doe@example.com

phone_code   string  optional  

The international phone code. Must match the regex /^+?\d{1,4}$/. Example: +44

phone   string  optional  

The phone number. Must match the regex /^+?\d[\d-]*$/. Must be at least 5 characters. Must not be greater than 20 characters. Example: 5551234567

reference_id   string  optional  

A customer's unique identifier. Must be at least 1 character. Must not be greater than 64 characters. Example: ABC123XYZ

date_of_birth   string  optional  

The date of birth. Must be a valid date in the format Y-m-d. Example: 2021-10-20

legal_entity   string  optional  

The legal status of the customer (PRIVATE/BUSINESS). Example: PRIVATE

Must be one of:
  • PRIVATE
  • BUSINESS
identifiers   object[]  optional  

An array of customer's unique identifiers belonging to specific gateways. Each object in the array must contain a numeric id, which represents the unique identifier, and a string gateway, which represents the name of the gateway.

id   string  optional  

The unique identifier. Example: 123456

gateway   string  optional  

The name of the gateway. Example: trustpay

Response

Response Fields

Response 200      

Successful response

customer_token   string   

A token identifying the customer. Example: 496d8b1f-916e-4f79-bab6-a09a223ecffb

first_name   string   

The first name of the customer. Example: John

last_name   string   

The last name of the customer. Example: Doe

jp_fullname   string   

The full name in Japanese. Example: ε±±η”° ε€ͺιƒŽ

street   string   

The street address. Example: 123 Maple Street

city   string   

The city of the address. Example: London

state   string   

The state of the address. Example: null

post_code   string   

The postal code of the address. Example: 94107

country   string   

The country code of the address. Example: GB

phone_code   string   

The international phone code. Example: +44

phone   string   

The phone number. Example: 5551234567

email   string   

The email address of the customer. Example: john.doe@example.com

reference_id   string   

A customer's unique identifier. Example: ABC123XYZ

date_of_birth   date   

The date of birth. Example: 2021-10-20

legal_entity   string   

The legal status of the customer (PRIVATE/BUSINESS). Example: PRIVATE

status   string   

This parameter indicates the current status of the customer within the system. Possible values: Active, Inactive. Example: Active

created   string   

This parameter indicates the date and time when the customer's record was initially created in the system. Example: 2024-06-04T10:06:57.000000Z

updated   string   

This parameter indicates the most recent date and time when the customer's record was updated. Example: 2024-06-04T10:06:57.000000Z

identifiers   Object[]   

An array of customer's unique identifiers belonging to specific gateways. Each object in the array must contain a numeric id, which represents the unique identifier, and a string gateway, which represents the name of the gateway.

id   string   

The unique identifier. Example: 123456

gateway   string   

The name of the gateway. Example: trustpay

banks   object[]   

An array of customer's banks.

bank_token   string   

A token identifying the bank account. Example: a6a6509b-26dc-49cc-b0e6-92c5d6eede36

customer_token   string   

A token identifying the customer who owns the bank account. Example: 496d8b1f-916e-4f79-bab6-a09a223ecffb

title   string   

The name of the bank account. Example: Bank Account

currency   string   

The currency code representing the currency in which the bank account is denominated. Example: USD

beneficiary_name   string   

The name of the account holder or the customer who owns the bank account. Example: John Doe

beneficiary_address   string   

The address of the account holder. Example: 123 Maple Street, London

bank_name   string   

The name of the bank where the customer's account is held. Example: Metro Bank

branch_name   string   

The name of the specific branch of the bank where the customer's account is maintained. Example: MetroBank

bank_address   string   

The address of the bank where the customer's account is held. Example: 123 Maple Street, London

bank_code   string   

The code that uniquely identifies the bank. Example: 0100

account_number   string   

The bank account number that uniquely identifies the customer's bank account. Example: 789456123

iban   string   

An international standard account number (IBAN) used to uniquely identify the customer's bank account for cross-border transactions. Example: GB23MBTC60161331926819

bic   string   

An international standard code (BIC/SWIFT) used to identify the customer's bank for cross-border transactions. Example: MBTCPHMMXXX

account_type   string   

The type of the bank account. Example: current

bank_clearing_system_code   string   

The bank clearing code (ISO 20022). Example: SGIBG

bank_clearing_system_id   string   

The bank clearing identifier (ISO 20022). Example: 1234567

Response 400|401|403|404|405|410|422      

Error response

error   string   

This parameter contains a message describing the error that occurred. Example: Invalid currency

code   integer   

This parameter provides a numeric code that uniquely identifies the specific error. Example: 100003

Status

requires authentication

To get information about the current status of a customer, call the status endpoint with the customer_token.

Example request:
curl --request GET \
    --get "https://secure.staging.paypipes.net/api/v2/customer/31e80148-746c-11e8-ad82-000d3a2b9844" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json (or application/x-www-form-url-encoded)"
const url = new URL(
    "https://secure.staging.paypipes.net/api/v2/customer/31e80148-746c-11e8-ad82-000d3a2b9844"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json (or application/x-www-form-url-encoded)",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://secure.staging.paypipes.net/api/v2/customer/31e80148-746c-11e8-ad82-000d3a2b9844';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json (or application/x-www-form-url-encoded)',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://secure.staging.paypipes.net/api/v2/customer/31e80148-746c-11e8-ad82-000d3a2b9844'
headers = {
  'Authorization': 'Bearer {ACCESS_TOKEN}',
  'Content-Type': 'application/json (or application/x-www-form-url-encoded)'
}

response = requests.request('GET', url, headers=headers)
response.json()

Example response (200, Successful response):


{
    "customer_token": "496d8b1f-916e-4f79-bab6-a09a223ecffb",
    "first_name": "John",
    "last_name": "Doe",
    "jp_fullname": "ε±±η”° ε€ͺιƒŽ",
    "street": "123 Maple Street",
    "city": "London",
    "state": null,
    "post_code": "94107",
    "country": "GB",
    "phone_code": "+44",
    "phone": "5551234567",
    "email": "john.doe@example.com",
    "reference_id": "ABC123XYZ",
    "date_of_birth": "2021-10-20",
    "legal_entity": "PRIVATE",
    "status": "Active",
    "created": "2024-06-04T10:06:57.000000Z",
    "updated": "2024-06-04T10:06:57.000000Z",
    "identifiers": [
        {
            "id": "123456",
            "gateway": "trustpay",
            "created": "2024-06-04T10:06:57.000000Z",
            "updated": "2024-06-04T10:06:57.000000Z"
        },
        {
            "id": "456789",
            "gateway": "unlimit",
            "created": "2024-06-04T10:06:57.000000Z",
            "updated": "2024-06-04T10:06:57.000000Z"
        }
    ],
    "banks": [
        {
            "bank_token": "a6a6509b-26dc-49cc-b0e6-92c5d6eede36",
            "customer_token": "496d8b1f-916e-4f79-bab6-a09a223ecffb",
            "title": "Bank Account",
            "currency": "USD",
            "beneficiary_name": "John Doe",
            "beneficiary_address": "123 Maple Street, London",
            "bank_name": "Metro Bank",
            "branch_name": "MetroBank",
            "bank_address": "123 Maple Street, London",
            "bank_code": "0100",
            "account_number": "789456123",
            "iban": "GB23MBTC60161331926819",
            "bic": "MBTCPHMMXXX",
            "account_type": "current",
            "bank_clearing_system_code": "SGIBG",
            "bank_clearing_system_id": "1234567"
        }
    ]
}
 

Example response (400, Error response):


{
    "error": "Bad request",
    "code": 200000
}
 

Example response (401, Error response):


{
    "error": "Unauthenticated",
    "code": 100001
}
 

Example response (403, Error response):


{
    "error": "Unauthorized",
    "code": 100004
}
 

Example response (404, Error response):


{
    "error": "Record not found",
    "code": 200007
}
 

Example response (405, Error response):


{
    "error": "The specified method for the request is invalid",
    "code": 200008
}
 

Example response (410, Error response):


{
    "error": "Transaction has expired (Transaction ID: #ID)",
    "code": 200037
}
 

Example response (422, Error response):


{
    "error": "Invalid currency",
    "code": 100003
}
 

Request      

GET api/v2/customer/{customer_token}

Headers

Authorization      

Example: Bearer {ACCESS_TOKEN}

Content-Type      

Example: application/json (or application/x-www-form-url-encoded)

URL Parameters

customer_token   string   

Customer token of the existing customer. Example: 31e80148-746c-11e8-ad82-000d3a2b9844

Response

Response Fields

Response 200      

Successful response

customer_token   string   

A token identifying the customer. Example: 496d8b1f-916e-4f79-bab6-a09a223ecffb

first_name   string   

The first name of the customer. Example: John

last_name   string   

The last name of the customer. Example: Doe

jp_fullname   string   

The full name in Japanese. Example: ε±±η”° ε€ͺιƒŽ

street   string   

The street address. Example: 123 Maple Street

city   string   

The city of the address. Example: London

state   string   

The state of the address. Example: null

post_code   string   

The postal code of the address. Example: 94107

country   string   

The country code of the address. Example: GB

phone_code   string   

The international phone code. Example: +44

phone   string   

The phone number. Example: 5551234567

email   string   

The email address of the customer. Example: john.doe@example.com

reference_id   string   

A customer's unique identifier. Example: ABC123XYZ

date_of_birth   date   

The date of birth. Example: 2021-10-20

legal_entity   string   

The legal status of the customer (PRIVATE/BUSINESS). Example: PRIVATE

status   string   

This parameter indicates the current status of the customer within the system. Possible values: Active, Inactive. Example: Active

created   string   

This parameter indicates the date and time when the customer's record was initially created in the system. Example: 2024-06-04T10:06:57.000000Z

updated   string   

This parameter indicates the most recent date and time when the customer's record was updated. Example: 2024-06-04T10:06:57.000000Z

identifiers   object[]   

An array of customer's unique identifiers belonging to specific gateways. Each object in the array must contain a numeric id, which represents the unique identifier, and a string gateway, which represents the name of the gateway.

id   string   

The unique identifier. Example: 123456

gateway   string   

The name of the gateway. Example: trustpay

banks   object[]   

An array of customer's banks.

bank_token   string   

A token identifying the bank account. Example: a6a6509b-26dc-49cc-b0e6-92c5d6eede36

customer_token   string   

A token identifying the customer who owns the bank account. Example: 496d8b1f-916e-4f79-bab6-a09a223ecffb

title   string   

The name of the bank account. Example: Bank Account

currency   string   

The currency code representing the currency in which the bank account is denominated. Example: USD

beneficiary_name   string   

The name of the account holder or the customer who owns the bank account. Example: John Doe

beneficiary_address   string   

The address of the account holder. Example: 123 Maple Street, London

bank_name   string   

The name of the bank where the customer's account is held. Example: Metro Bank

branch_name   string   

The name of the specific branch of the bank where the customer's account is maintained. Example: MetroBank

bank_address   string   

The address of the bank where the customer's account is held. Example: 123 Maple Street, London

bank_code   string   

The code that uniquely identifies the bank. Example: 0100

account_number   string   

The bank account number that uniquely identifies the customer's bank account. Example: 789456123

iban   string   

An international standard account number (IBAN) used to uniquely identify the customer's bank account for cross-border transactions. Example: GB23MBTC60161331926819

bic   string   

An international standard code (BIC/SWIFT) used to identify the customer's bank for cross-border transactions. Example: MBTCPHMMXXX

account_type   string   

The type of the bank account. Example: current

bank_clearing_system_code   string   

The bank clearing code (ISO 20022). Example: SGIBG

bank_clearing_system_id   string   

The bank clearing identifier (ISO 20022). Example: 1234567

Response 400|401|403|404|405|410|422      

Error response.

error   string   

This parameter contains a message describing the error that occurred. Example: Invalid currency

code   int   

This parameter provides a numeric code that uniquely identifies the specific error. Example: 100003

Bank

Create

requires authentication

A tokenize bank request transforms bank data into a token. This request is sent by making a POST request over HTTPS to the /tokenize/banks endpoint.

Example request:
curl --request POST \
    "https://secure.staging.paypipes.net/api/v2/tokenize/banks" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json (or application/x-www-form-url-encoded)" \
    --data "{
    \"customer_token\": \"496d8b1f-916e-4f79-bab6-a09a223ecffb\",
    \"title\": \"Bank Account\",
    \"currency\": \"USD\",
    \"beneficiary_name\": \"John Doe\",
    \"beneficiary_address\": \"123 Maple Street, London\",
    \"bank_name\": \"Metro Bank\",
    \"branch_name\": \"MetroBank\",
    \"bank_address\": \"123 Maple Street, London\",
    \"bank_code\": \"0100\",
    \"bank_country\": \"CZ\",
    \"account_number\": 789456123,
    \"iban\": \"GB23MBTC60161331926819\",
    \"bic\": \"MBTCPHMMXXX\",
    \"account_type\": \"current\",
    \"bank_clearing_system_code\": \"SGIBG\",
    \"bank_clearing_system_id\": \"1234567\"
}"
const url = new URL(
    "https://secure.staging.paypipes.net/api/v2/tokenize/banks"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json (or application/x-www-form-url-encoded)",
    "Accept": "application/json",
};

let body = {
    "customer_token": "496d8b1f-916e-4f79-bab6-a09a223ecffb",
    "title": "Bank Account",
    "currency": "USD",
    "beneficiary_name": "John Doe",
    "beneficiary_address": "123 Maple Street, London",
    "bank_name": "Metro Bank",
    "branch_name": "MetroBank",
    "bank_address": "123 Maple Street, London",
    "bank_code": "0100",
    "bank_country": "CZ",
    "account_number": 789456123,
    "iban": "GB23MBTC60161331926819",
    "bic": "MBTCPHMMXXX",
    "account_type": "current",
    "bank_clearing_system_code": "SGIBG",
    "bank_clearing_system_id": "1234567"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://secure.staging.paypipes.net/api/v2/tokenize/banks';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json (or application/x-www-form-url-encoded)',
        ],
        'json' => [
            'customer_token' => '496d8b1f-916e-4f79-bab6-a09a223ecffb',
            'title' => 'Bank Account',
            'currency' => 'USD',
            'beneficiary_name' => 'John Doe',
            'beneficiary_address' => '123 Maple Street, London',
            'bank_name' => 'Metro Bank',
            'branch_name' => 'MetroBank',
            'bank_address' => '123 Maple Street, London',
            'bank_code' => '0100',
            'bank_country' => 'CZ',
            'account_number' => 789456123.0,
            'iban' => 'GB23MBTC60161331926819',
            'bic' => 'MBTCPHMMXXX',
            'account_type' => 'current',
            'bank_clearing_system_code' => 'SGIBG',
            'bank_clearing_system_id' => '1234567',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://secure.staging.paypipes.net/api/v2/tokenize/banks'
payload = {
    "customer_token": "496d8b1f-916e-4f79-bab6-a09a223ecffb",
    "title": "Bank Account",
    "currency": "USD",
    "beneficiary_name": "John Doe",
    "beneficiary_address": "123 Maple Street, London",
    "bank_name": "Metro Bank",
    "branch_name": "MetroBank",
    "bank_address": "123 Maple Street, London",
    "bank_code": "0100",
    "bank_country": "CZ",
    "account_number": 789456123,
    "iban": "GB23MBTC60161331926819",
    "bic": "MBTCPHMMXXX",
    "account_type": "current",
    "bank_clearing_system_code": "SGIBG",
    "bank_clearing_system_id": "1234567"
}
headers = {
  'Authorization': 'Bearer {ACCESS_TOKEN}',
  'Content-Type': 'application/json (or application/x-www-form-url-encoded)'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (201, Successful response):


{
    "bank_token": "a6a6509b-26dc-49cc-b0e6-92c5d6eede36",
    "customer_token": "496d8b1f-916e-4f79-bab6-a09a223ecffb",
    "title": "Bank Account",
    "currency": "USD",
    "beneficiary_name": "John Doe",
    "beneficiary_address": "123 Maple Street, London",
    "bank_name": "Metro Bank",
    "branch_name": "MetroBank",
    "bank_address": "123 Maple Street, London",
    "bank_code": "0100",
    "bank_country": "CZ",
    "account_number": "789456123",
    "iban": "GB23MBTC60161331926819",
    "bic": "MBTCPHMMXXX",
    "account_type": "current",
    "bank_clearing_system_code": "SGIBG",
    "bank_clearing_system_id": "1234567"
}
 

Example response (400, Error response):


{
    "error": "Bad request",
    "code": 200000
}
 

Example response (401, Error response):


{
    "error": "Unauthenticated",
    "code": 100001
}
 

Example response (403, Error response):


{
    "error": "Unauthorized",
    "code": 100004
}
 

Example response (405, Error response):


{
    "error": "The specified method for the request is invalid",
    "code": 200008
}
 

Example response (422, Error response):


{
    "error": "Invalid currency",
    "code": 100003
}
 

Request      

POST api/v2/tokenize/banks

Headers

Authorization      

Example: Bearer {ACCESS_TOKEN}

Content-Type      

Example: application/json (or application/x-www-form-url-encoded)

Body Parameters

customer_token   string   

A token identifying the customer who owns the bank account. This field is required. Example: 496d8b1f-916e-4f79-bab6-a09a223ecffb

title   string   

The name of the bank account. This field is required. Must not be greater than 100 characters. Example: Bank Account

currency   string   

The currency code representing the currency in which the bank account is denominated. The cy_code of an existing record in the currencies table. Example: USD

beneficiary_name   string   

The name of the account holder or the customer who owns the bank account. Must not be greater than 255 characters. Example: John Doe

beneficiary_address   string  optional  

The address of the account holder. This field is required when iban is present. Must not be greater than 255 characters. Example: 123 Maple Street, London

bank_name   string   

The name of the bank where the customer's account is held. Must not be greater than 255 characters. Example: Metro Bank

branch_name   string  optional  

The name of the specific branch of the bank where the customer's account is maintained. This field is required when account_number is present. Must not be greater than 255 characters. Example: MetroBank

bank_address   string  optional  

The address of the bank where the customer's account is held. This field is required when iban is present. Must not be greater than 255 characters. Example: 123 Maple Street, London

bank_code   string  optional  

The code that uniquely identifies the bank. This field is required when account_number is present. Must not be greater than 20 characters. Example: 0100

bank_country   string  optional  

The country code of the bank. The country_code of an existing record in the countries table. Must not be greater than 2 characters. Example: CZ

account_number   number  optional  

The bank account number that uniquely identifies the customer's bank account. This field is required when iban is not present. Example: 789456123

iban   string  optional  

An international standard account number (IBAN) used to uniquely identify the customer's bank account for cross-border transactions. This field is required when account_number is not present. Must not be greater than 50 characters. Example: GB23MBTC60161331926819

bic   string  optional  

An international standard code (BIC/SWIFT) used to identify the customer's bank for cross-border transactions. Must not be greater than 20 characters. Example: MBTCPHMMXXX

account_type   string  optional  

The type of the bank account. Example: current

Must be one of:
  • current
  • savings
  • checking
bank_clearing_system_code   string  optional  

The bank clearing code (ISO 20022). Example: SGIBG

Must be one of:
  • ATBLZ
  • AUBSB
  • CACPA
  • CHBCC
  • CHSIC
  • CNAPS
  • DEBLZ
  • ESNCC
  • GBDSC
  • GRBIC
  • HKNCC
  • IENCC
  • INFSC
  • ITNCC
  • JPZGN
  • NZNCC
  • PLKNR
  • PTNCC
  • RUCBC
  • SESBA
  • SGIBG
  • TWNCC
  • USABA
  • USPID
  • ZANCC
bank_clearing_system_id   string  optional  

The bank clearing identifier (ISO 20022).

clearing codeclearing ID validation mask
ATBLZ[0-9]{5,5}
AUBSB[0-9]{6,6}
CACPA[0-9]{9,9}
CHBCC[0-9]{3,5}
CHSIC[0-9]{6,6}
CNAPS[0-9]{12,12}
DEBLZ[0-9]{8,8}
ESNCC[0-9]{8,9}
GBDSC[0-9]{6,6}
GRBIC[0-9]{7,7}
HKNCC[0-9]{3,3}
IENCC[0-9]{6,6}
INFSC[a-zA-Z0-9]{11,11}
ITNCC[0-9]{10,10}
JPZGN[0-9]{7,7}
NZNCC[0-9]{6,6}
PLKNR[0-9]{8,8}
PTNCC[0-9]{8,8}
RUCBC[0-9]{9,9}
SESBA[0-9]{4,4}
SGIBG[0-9]{7,7} or [0-9]{3,4}
TWNCC[0-9]{7,7}
USABA[0-9]{9,9}
USPID[0-9]{4,4}
ZANCC[0-9]{6,6}
Regexp validation masks. Example: 1234567

Response

Response Fields

Response 201      

Successful response

bank_token   string   

A token identifying the bank account. Example: a6a6509b-26dc-49cc-b0e6-92c5d6eede36

customer_token   string   

A token identifying the customer who owns the bank account. Example: 496d8b1f-916e-4f79-bab6-a09a223ecffb

title   string   

The name of the bank account. Example: Bank Account

currency   string   

The currency code representing the currency in which the bank account is denominated. Example: USD

beneficiary_name   string   

The name of the account holder or the customer who owns the bank account. Example: John Doe

beneficiary_address   string   

The address of the account holder. Example: 123 Maple Street, London

bank_name   string   

The name of the bank where the customer's account is held. Example: Metro Bank

branch_name   string   

The name of the specific branch of the bank where the customer's account is maintained. Example: MetroBank

bank_address   string   

The address of the bank where the customer's account is held. Example: 123 Maple Street, London

bank_code   string   

The code that uniquely identifies the bank. Example: 0100

bank_country   string   

The country code of the bank. Example: CZ

account_number   string   

The bank account number that uniquely identifies the customer's bank account. Example: 789456123

iban   string   

An international standard account number (IBAN) used to uniquely identify the customer's bank account for cross-border transactions. Example: GB23MBTC60161331926819

bic   string   

An international standard code (BIC/SWIFT) used to identify the customer's bank for cross-border transactions. Example: MBTCPHMMXXX

account_type   string   

The type of the bank account. Example: current

bank_clearing_system_code   string   

The bank clearing code (ISO 20022). Example: SGIBG

bank_clearing_system_id   string   

The bank clearing identifier (ISO 20022). Example: 1234567

Response 400|401|403|405|422      

Error response

error   string   

This parameter contains a message describing the error that occurred. Example: Invalid currency

code   integer   

This parameter provides a numeric code that uniquely identifies the specific error. Example: 100003

Update

requires authentication

You can update a bank account by sending a PATCH request over HTTPS to the /tokenize/banks/{bank_token} endpoint.

Example request:
curl --request PATCH \
    "https://secure.staging.paypipes.net/api/v2/tokenize/banks/a6a6509b-26dc-49cc-b0e6-92c5d6eede36" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json (or application/x-www-form-url-encoded)" \
    --data "{
    \"customer_token\": \"496d8b1f-916e-4f79-bab6-a09a223ecffb\",
    \"title\": \"Bank Account\",
    \"currency\": \"USD\",
    \"beneficiary_name\": \"John Doe\",
    \"beneficiary_address\": \"123 Maple Street, London\",
    \"bank_name\": \"Metro Bank\",
    \"branch_name\": \"MetroBank\",
    \"bank_address\": \"123 Maple Street, London\",
    \"bank_code\": \"0100\",
    \"bank_country\": \"CZ\",
    \"account_number\": 789456123,
    \"iban\": \"GB23MBTC60161331926819\",
    \"bic\": \"MBTCPHMMXXX\",
    \"account_type\": \"current\",
    \"bank_clearing_system_code\": \"SGIBG\",
    \"bank_clearing_system_id\": \"1234567\"
}"
const url = new URL(
    "https://secure.staging.paypipes.net/api/v2/tokenize/banks/a6a6509b-26dc-49cc-b0e6-92c5d6eede36"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json (or application/x-www-form-url-encoded)",
    "Accept": "application/json",
};

let body = {
    "customer_token": "496d8b1f-916e-4f79-bab6-a09a223ecffb",
    "title": "Bank Account",
    "currency": "USD",
    "beneficiary_name": "John Doe",
    "beneficiary_address": "123 Maple Street, London",
    "bank_name": "Metro Bank",
    "branch_name": "MetroBank",
    "bank_address": "123 Maple Street, London",
    "bank_code": "0100",
    "bank_country": "CZ",
    "account_number": 789456123,
    "iban": "GB23MBTC60161331926819",
    "bic": "MBTCPHMMXXX",
    "account_type": "current",
    "bank_clearing_system_code": "SGIBG",
    "bank_clearing_system_id": "1234567"
};

fetch(url, {
    method: "PATCH",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://secure.staging.paypipes.net/api/v2/tokenize/banks/a6a6509b-26dc-49cc-b0e6-92c5d6eede36';
$response = $client->patch(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json (or application/x-www-form-url-encoded)',
        ],
        'json' => [
            'customer_token' => '496d8b1f-916e-4f79-bab6-a09a223ecffb',
            'title' => 'Bank Account',
            'currency' => 'USD',
            'beneficiary_name' => 'John Doe',
            'beneficiary_address' => '123 Maple Street, London',
            'bank_name' => 'Metro Bank',
            'branch_name' => 'MetroBank',
            'bank_address' => '123 Maple Street, London',
            'bank_code' => '0100',
            'bank_country' => 'CZ',
            'account_number' => 789456123.0,
            'iban' => 'GB23MBTC60161331926819',
            'bic' => 'MBTCPHMMXXX',
            'account_type' => 'current',
            'bank_clearing_system_code' => 'SGIBG',
            'bank_clearing_system_id' => '1234567',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://secure.staging.paypipes.net/api/v2/tokenize/banks/a6a6509b-26dc-49cc-b0e6-92c5d6eede36'
payload = {
    "customer_token": "496d8b1f-916e-4f79-bab6-a09a223ecffb",
    "title": "Bank Account",
    "currency": "USD",
    "beneficiary_name": "John Doe",
    "beneficiary_address": "123 Maple Street, London",
    "bank_name": "Metro Bank",
    "branch_name": "MetroBank",
    "bank_address": "123 Maple Street, London",
    "bank_code": "0100",
    "bank_country": "CZ",
    "account_number": 789456123,
    "iban": "GB23MBTC60161331926819",
    "bic": "MBTCPHMMXXX",
    "account_type": "current",
    "bank_clearing_system_code": "SGIBG",
    "bank_clearing_system_id": "1234567"
}
headers = {
  'Authorization': 'Bearer {ACCESS_TOKEN}',
  'Content-Type': 'application/json (or application/x-www-form-url-encoded)'
}

response = requests.request('PATCH', url, headers=headers, json=payload)
response.json()

Example response (200, Successful response):


{
    "bank_token": "a6a6509b-26dc-49cc-b0e6-92c5d6eede36",
    "customer_token": "496d8b1f-916e-4f79-bab6-a09a223ecffb",
    "title": "Bank Account",
    "currency": "USD",
    "beneficiary_name": "John Doe",
    "beneficiary_address": "123 Maple Street, London",
    "bank_name": "Metro Bank",
    "branch_name": "MetroBank",
    "bank_address": "123 Maple Street, London",
    "bank_code": "0100",
    "bank_country": "CZ",
    "account_number": "789456123",
    "iban": "GB23MBTC60161331926819",
    "bic": "MBTCPHMMXXX",
    "account_type": "current",
    "bank_clearing_system_code": "SGIBG",
    "bank_clearing_system_id": "1234567"
}
 

Example response (400, Error response):


{
    "error": "Bad request",
    "code": 200000
}
 

Example response (401, Error response):


{
    "error": "Unauthenticated",
    "code": 100001
}
 

Example response (403, Error response):


{
    "error": "Unauthorized",
    "code": 100004
}
 

Example response (404, Error response):


{
    "error": "Record not found",
    "code": 200007
}
 

Example response (405, Error response):


{
    "error": "The specified method for the request is invalid",
    "code": 200008
}
 

Example response (422, Error response):


{
    "error": "Invalid currency",
    "code": 100003
}
 

Request      

PATCH api/v2/tokenize/banks/{customerBank_bank_token}

Headers

Authorization      

Example: Bearer {ACCESS_TOKEN}

Content-Type      

Example: application/json (or application/x-www-form-url-encoded)

URL Parameters

customerBank_bank_token   string   

Bank token of the existing bank account. Example: a6a6509b-26dc-49cc-b0e6-92c5d6eede36

Body Parameters

customer_token   string  optional  

A token identifying the customer who owns the bank account. Example: 496d8b1f-916e-4f79-bab6-a09a223ecffb

title   string  optional  

The name of the bank account. Must not be greater than 100 characters. Example: Bank Account

currency   string  optional  

The currency code representing the currency in which the bank account is denominated. The cy_code of an existing record in the currencies table. Example: USD

beneficiary_name   string  optional  

The name of the account holder or the customer who owns the bank account. Must not be greater than 255 characters. Example: John Doe

beneficiary_address   string  optional  

The address of the account holder. Must not be greater than 255 characters. Example: 123 Maple Street, London

bank_name   string  optional  

The name of the bank where the customer's account is held. Must not be greater than 255 characters. Example: Metro Bank

branch_name   string  optional  

The name of the specific branch of the bank where the customer's account is maintained. Must not be greater than 255 characters. Example: MetroBank

bank_address   string  optional  

The address of the bank where the customer's account is held. Must not be greater than 255 characters. Example: 123 Maple Street, London

bank_code   string  optional  

The code that uniquely identifies the bank. Must not be greater than 20 characters. Example: 0100

bank_country   string  optional  

The country code of the bank. The country_code of an existing record in the countries table. Must not be greater than 2 characters. Example: CZ

account_number   number  optional  

The bank account number that uniquely identifies the customer's bank account. Example: 789456123

iban   string  optional  

An international standard account number (IBAN) used to uniquely identify the customer's bank account for cross-border transactions. Must not be greater than 50 characters. Example: GB23MBTC60161331926819

bic   string  optional  

An international standard code (BIC/SWIFT) used to identify the customer's bank for cross-border transactions. Must not be greater than 20 characters. Example: MBTCPHMMXXX

account_type   string  optional  

The type of the bank account. Example: current

Must be one of:
  • current
  • savings
  • checking
bank_clearing_system_code   string  optional  

The bank clearing code (ISO 20022). Example: SGIBG

Must be one of:
  • ATBLZ
  • AUBSB
  • CACPA
  • CHBCC
  • CHSIC
  • CNAPS
  • DEBLZ
  • ESNCC
  • GBDSC
  • GRBIC
  • HKNCC
  • IENCC
  • INFSC
  • ITNCC
  • JPZGN
  • NZNCC
  • PLKNR
  • PTNCC
  • RUCBC
  • SESBA
  • SGIBG
  • TWNCC
  • USABA
  • USPID
  • ZANCC
bank_clearing_system_id   string  optional  

The bank clearing identifier (ISO 20022).

clearing codeclearing ID validation mask
ATBLZ[0-9]{5,5}
AUBSB[0-9]{6,6}
CACPA[0-9]{9,9}
CHBCC[0-9]{3,5}
CHSIC[0-9]{6,6}
CNAPS[0-9]{12,12}
DEBLZ[0-9]{8,8}
ESNCC[0-9]{8,9}
GBDSC[0-9]{6,6}
GRBIC[0-9]{7,7}
HKNCC[0-9]{3,3}
IENCC[0-9]{6,6}
INFSC[a-zA-Z0-9]{11,11}
ITNCC[0-9]{10,10}
JPZGN[0-9]{7,7}
NZNCC[0-9]{6,6}
PLKNR[0-9]{8,8}
PTNCC[0-9]{8,8}
RUCBC[0-9]{9,9}
SESBA[0-9]{4,4}
SGIBG[0-9]{7,7} or [0-9]{3,4}
TWNCC[0-9]{7,7}
USABA[0-9]{9,9}
USPID[0-9]{4,4}
ZANCC[0-9]{6,6}
Regexp validation masks. Example: 1234567

Response

Response Fields

Response 200      

Successful response

bank_token   string   

A token identifying the bank account. Example: a6a6509b-26dc-49cc-b0e6-92c5d6eede36

customer_token   string   

A token identifying the customer who owns the bank account. Example: 496d8b1f-916e-4f79-bab6-a09a223ecffb

title   string   

The name of the bank account. Example: Bank Account

currency   string   

The currency code representing the currency in which the bank account is denominated. Example: USD

beneficiary_name   string   

The name of the account holder or the customer who owns the bank account. Example: John Doe

beneficiary_address   string   

The address of the account holder. Example: 123 Maple Street, London

bank_name   string   

The name of the bank where the customer's account is held. Example: Metro Bank

branch_name   string   

The name of the specific branch of the bank where the customer's account is maintained. Example: MetroBank

bank_address   string   

The address of the bank where the customer's account is held. Example: 123 Maple Street, London

bank_code   string   

The code that uniquely identifies the bank. Example: 0100

bank_country   string   

The country code of the bank. Example: CZ

account_number   string   

The bank account number that uniquely identifies the customer's bank account. Example: 789456123

iban   string   

An international standard account number (IBAN) used to uniquely identify the customer's bank account for cross-border transactions. Example: GB23MBTC60161331926819

bic   string   

An international standard code (BIC/SWIFT) used to identify the customer's bank for cross-border transactions. Example: MBTCPHMMXXX

account_type   string   

The type of the bank account. Example: current

bank_clearing_system_code   string   

The bank clearing code (ISO 20022). Example: SGIBG

bank_clearing_system_id   string   

The bank clearing identifier (ISO 20022). Example: 1234567

Response 400|401|403|404|405|422      

Error response

error   string   

This parameter contains a message describing the error that occurred. Example: Invalid currency

code   integer   

This parameter provides a numeric code that uniquely identifies the specific error. Example: 100003

Status

requires authentication

To get information about the current status of a bank account, call the status endpoint with the bank_token.

Example request:
curl --request GET \
    --get "https://secure.staging.paypipes.net/api/v2/bank/a6a6509b-26dc-49cc-b0e6-92c5d6eede36" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json (or application/x-www-form-url-encoded)"
const url = new URL(
    "https://secure.staging.paypipes.net/api/v2/bank/a6a6509b-26dc-49cc-b0e6-92c5d6eede36"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json (or application/x-www-form-url-encoded)",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://secure.staging.paypipes.net/api/v2/bank/a6a6509b-26dc-49cc-b0e6-92c5d6eede36';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json (or application/x-www-form-url-encoded)',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://secure.staging.paypipes.net/api/v2/bank/a6a6509b-26dc-49cc-b0e6-92c5d6eede36'
headers = {
  'Authorization': 'Bearer {ACCESS_TOKEN}',
  'Content-Type': 'application/json (or application/x-www-form-url-encoded)'
}

response = requests.request('GET', url, headers=headers)
response.json()

Example response (200, Successful response):


{
    "bank_token": "a6a6509b-26dc-49cc-b0e6-92c5d6eede36",
    "customer_token": "496d8b1f-916e-4f79-bab6-a09a223ecffb",
    "title": "Bank Account",
    "currency": "USD",
    "beneficiary_name": "John Doe",
    "beneficiary_address": "123 Maple Street, London",
    "bank_name": "Metro Bank",
    "branch_name": "MetroBank",
    "bank_address": "123 Maple Street, London",
    "bank_code": "0100",
    "account_number": "789456123",
    "iban": "GB23MBTC60161331926819",
    "bic": "MBTCPHMMXXX",
    "account_type": "current",
    "bank_clearing_system_code": "SGIBG",
    "bank_clearing_system_id": "1234567"
}
 

Example response (400, Error response):


{
    "error": "Bad request",
    "code": 200000
}
 

Example response (401, Error response):


{
    "error": "Unauthenticated",
    "code": 100001
}
 

Example response (403, Error response):


{
    "error": "Unauthorized",
    "code": 100004
}
 

Example response (404, Error response):


{
    "error": "Record not found",
    "code": 200007
}
 

Example response (405, Error response):


{
    "error": "The specified method for the request is invalid",
    "code": 200008
}
 

Example response (422, Error response):


{
    "error": "Invalid currency",
    "code": 100003
}
 

Request      

GET api/v2/bank/{bank_token}

Headers

Authorization      

Example: Bearer {ACCESS_TOKEN}

Content-Type      

Example: application/json (or application/x-www-form-url-encoded)

URL Parameters

bank_token   string   

Bank token of the existing bank account. Example: a6a6509b-26dc-49cc-b0e6-92c5d6eede36

Response

Response Fields

Response 200      

Successful response

bank_token   string   

A token identifying the bank account. Example: a6a6509b-26dc-49cc-b0e6-92c5d6eede36

customer_token   string   

A token identifying the customer who owns the bank account. Example: 496d8b1f-916e-4f79-bab6-a09a223ecffb

title   string   

The name of the bank account. Example: Bank Account

currency   string   

The currency code representing the currency in which the bank account is denominated. Example: USD

beneficiary_name   string   

The name of the account holder or the customer who owns the bank account. Example: John Doe

beneficiary_address   string   

The address of the account holder. Example: 123 Maple Street, London

bank_name   string   

The name of the bank where the customer's account is held. Example: Metro Bank

branch_name   string   

The name of the specific branch of the bank where the customer's account is maintained. Example: MetroBank

bank_address   string   

The address of the bank where the customer's account is held. Example: 123 Maple Street, London

bank_code   string   

The code that uniquely identifies the bank. Example: 0100

account_number   string   

The bank account number that uniquely identifies the customer's bank account. Example: 789456123

iban   string   

An international standard account number (IBAN) used to uniquely identify the customer's bank account for cross-border transactions. Example: GB23MBTC60161331926819

bic   string   

An international standard code (BIC/SWIFT) used to identify the customer's bank for cross-border transactions. Example: MBTCPHMMXXX

account_type   string   

The type of the bank account. Example: current

bank_clearing_system_code   string   

The bank clearing code (ISO 20022). Example: SGIBG

bank_clearing_system_id   string   

The bank clearing identifier (ISO 20022). Example: 1234567

Response 400|401|403|404|405|422      

Error response.

error   string   

This parameter contains a message describing the error that occurred. Example: Invalid currency

code   int   

This parameter provides a numeric code that uniquely identifies the specific error. Example: 100003

Payment Methods

Get payment methods

requires authentication

The payment methods endpoint returns available payment methods on the particular terminal by sending a GET request over HTTPS to the /payment-methods.

Example request:
curl --request GET \
    --get "https://secure.staging.paypipes.net/api/v2/payment-methods" \
    --header "Authorization: Bearer {ACCESS_TOKEN}" \
    --header "Content-Type: application/json (or application/x-www-form-url-encoded)"
const url = new URL(
    "https://secure.staging.paypipes.net/api/v2/payment-methods"
);

const headers = {
    "Authorization": "Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json (or application/x-www-form-url-encoded)",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://secure.staging.paypipes.net/api/v2/payment-methods';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {ACCESS_TOKEN}',
            'Content-Type' => 'application/json (or application/x-www-form-url-encoded)',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://secure.staging.paypipes.net/api/v2/payment-methods'
headers = {
  'Authorization': 'Bearer {ACCESS_TOKEN}',
  'Content-Type': 'application/json (or application/x-www-form-url-encoded)'
}

response = requests.request('GET', url, headers=headers)
response.json()

Example response (200, Successful response):


{
    "card": {
        "czk": [
            "jcb",
            "maestro",
            "mastercard",
            "visa"
        ],
        "eur": [
            "jcb",
            "maestro",
            "mastercard",
            "unionpay",
            "visa"
        ],
        "gbp": [
            "maestro",
            "mastercard",
            "visa"
        ],
        "jpy": [
            "jcb",
            "maestro",
            "mastercard",
            "unionpay",
            "visa"
        ],
        "ngn": [
            "mastercard",
            "verve",
            "visa"
        ],
        "pln": [
            "maestro",
            "mastercard",
            "visa"
        ],
        "usd": [
            "jcb",
            "maestro",
            "mastercard",
            "unionpay",
            "visa"
        ]
    },
    "wire": true,
    "wallet": [
        "skrill",
        "neteller"
    ],
    "crypto": [
        "confirmo"
    ]
}
 

Example response (400, Error response):


{
    "error": "Bad request",
    "code": 200000
}
 

Example response (401, Error response):


{
    "error": "Unauthenticated",
    "code": 100001
}
 

Example response (403, Error response):


{
    "error": "Unauthorized",
    "code": 100004
}
 

Example response (404, Error response):


{
    "error": "Record not found",
    "code": 200007
}
 

Example response (405, Error response):


{
    "error": "The specified method for the request is invalid",
    "code": 200008
}
 

Example response (410, Error response):


{
    "error": "Transaction has expired (Transaction ID: #ID)",
    "code": 200037
}
 

Example response (422, Error response):


{
    "error": "Invalid currency",
    "code": 100003
}
 

Request      

GET api/v2/payment-methods

Headers

Authorization      

Example: Bearer {ACCESS_TOKEN}

Content-Type      

Example: application/json (or application/x-www-form-url-encoded)

Response

Response Fields

Response 200      

Successful response

card   object   

An associative array mapping supported currencies to their respective card brands for card-based payment methods.

wire   boolean   

Boolean flag indicating the availability of the wire transfer payment method.

wallet   string[]   

An array listing supported wallet-based payment methods.

crypto   string[]   

An array listing supported crypto-based payment methods.

Response 400|401|403|404|405|410|422      

Error response

error   string   

This parameter contains a message describing the error that occurred. Example: Invalid currency

code   integer   

This parameter provides a numeric code that uniquely identifies the specific error. Example: 100003

Webhooks

A Signature value is included in the request header when sending the webhook response to the merchant for added security. This allows the merchant to verify the authenticity of the callback response from PayPipes.

To verify the signature:

  1. Use the client secret as the key for encrypting the payload to calculate the checksum.
  2. The payload is the body content of the webhook.
  3. Apply the HMAC SHA512 algorithm for encryption.

The calculated signature should match the Signature value in the request header to confirm the authenticity of the webhook response.

public function verifySignature(Request $request, string $payload, string $client_secret): bool
{
    return $request->header('signature') === hash_hmac('sha512', $payload, $client_secret);
}
        

Webhook example

Webhook example
{
    "version": 2,
    "orderID": "8c99g9d4-1eb0-428a-a4fa-dc595553c456",
    "trxID": "9170ced4-91a2-4d7d-a9e4-41431ee238f5",
    "trxType": "Purchase",
    "amount": "7610.84",
    "currency": "USD",
    "status": "Approved",
    "paymentStatus": null,
    "statusCode": "000.100.112",
    "statusDescription": "Request successfully processed.",
    "declineCode": null,
    "created": "2024-06-07T13:29:38.000000Z",
    "cardToken": "997E885B186GFBEABC92F0D20007",
    "customerToken": "f80h7806-a180-4523-17f9-ld58c4d177d4",
    "description": "Payment test description",
    "gateway": "trustpay",
    "applePay": false,
    "googlePay": false,
    "refNo": "5743899164",
    "requestID": "9170eas3-92a3-4d5e-a9e4-59813ee238f",
    "authCode": "p86xAqlXz",
    "card": {
        "holder": "John Doe",
        "bin": "520000",
        "digit": "0007",
        "brand": "mastercard",
        "cardLevel": "STANDARD",
        "expired": "12/2025",
        "maskNumber": "5200 00XX XXXX 0007"
    },
    "bank": null,
    "customerBank": {
        "bank_token": "a6a6509b-26dc-49cc-b0e6-92c5d6eede36",
        "customer_token": "f80h7806-a180-4523-17f9-ld58c4d177d4",
        "title": "Bank Account",
        "currency": "USD",
        "beneficiary_name": "John Doe",
        "beneficiary_address": "123 Maple Street, London",
        "bank_name": "Metro Bank",
        "branch_name": "MetroBank",
        "bank_address": "123 Maple Street, London",
        "bank_code": "0100",
        "account_number": "789456123",
        "iban": "GB23MBTC60161331926819",
        "bic": "MBTCPHMMXXX",
        "account_type": "current",
        "bank_clearing_system_code": "SGIBG",
        "bank_clearing_system_id'": "1234567",
    },
    "fees": null,
    "meta": null
}

Response Fields

version   int   

Indicates the version of the API. Example: 2

orderID   string   

Merchant's internal unique ID for the transaction. Example: 8c99g9d4-1eb0-428a-a4fa-dc595553c456

trxID   string   

A unique identifier for the transaction. Example: 9170ced4-91a2-4d7d-a9e4-41431ee238f5

trxType   string   

Specifies the type of the transaction. Allowed values: Purchase, Reverse, Refund. Example: Purchase

amount   string   

The value representing the actual amount for the transaction. Format: DECIMAL(20,2) Example: 7610.84

currency   string   

The currency code for the transaction, complies with the ISO 4217 standard. Example: USD

status   string   

The current status of the transaction. Allowed values: Approved, Declined, Cancelled. Example: Approved

paymentStatus   string   

Additional status information regarding the payment, if available. Allowed values: Refunded, Partially refunded. Example: null

statusCode   string   

A code representing the detailed status of the transaction. Typically, this code is provided directly by the third-party gateway. In some instances, such as an internal error, an error code from our predefined list will be displayed. Example: 000.100.112

statusDescription   string   

A textual description of the status code. Example: Request successfully processed.

declineCode   string   

Paypipes decline code. See Decline Codes table.

created   string   

The timestamp when the transaction was created. Example: 2024-06-07T13:29:38.000000Z

cardToken   string   

A token representing the customer's card information. Example: 997E885B186GFBEABC92F0D20007

customerToken   string   

A token representing the customer. Example: f80h7806-a180-4523-17f9-ld58c4d177d4

description   string   

A description of the transaction. Example: Payment test description

gateway   string   

The payment gateway used to process the transaction. Allowed values: Gateways Example: trustpay

applePay   boolean   

Indicates whether Apple Pay was used for the transaction. Example: false

googlePay   boolean   

Indicates whether Google Pay was used for the transaction. Example: false

refNo   string   

A reference number for the transaction, received from the third-party gateway. Example: 5743899164

requestID   string   

A unique identifier for the request associated with the transaction. This ID is sent to the third-party gateway. Example: 9170eas3-92a3-4d5e-a9e4-59813ee238f

authCode   string   

The authorization code for the transaction, if applicable. Example: p86xAqlXz

card  Card    

Contains details about the card used for the transaction.

holder   string   

The name of the cardholder. Example: John Doe

bin   string   

The Bank Identification Number of the card. Example: 520000

digit   string   

The last four digits of the card number. Example: 0007

brand   string   

The brand of the card (e.g., Visa, Mastercard). Example: mastercard

cardLevel   string|null   

The level or type of the card. Example: STANDARD

expired   string   

The expiration date of the card. Example: 12/2025

maskNumber   string   

The masked card number for security purposes. Example: 5200 00XX XXXX 0007

bank   Object   

Additional information about the bank account which was used for deposit. Example: null

customerBank  CustomerBank    

Contains detailed information about the customer's bank account.

bank_token   string   

A token identifying the bank account. Example: a6a6509b-26dc-49cc-b0e6-92c5d6eede36

customer_token   string   

A token identifying the customer who owns the bank account. Example: 496d8b1f-916e-4f79-bab6-a09a223ecffb

title   string   

The name of the bank account. Example: Bank Account

currency   string   

The currency code representing the currency in which the bank account is denominated. Example: USD

beneficiary_name   string   

The name of the account holder or the customer who owns the bank account. Example: John Doe

beneficiary_address   string   

The address of the account holder. Example: 123 Maple Street, London

bank_name   string   

The name of the bank where the customer's account is held. Example: Metro Bank

branch_name   string   

The name of the specific branch of the bank where the customer's account is maintained. Example: MetroBank

bank_address   string   

The address of the bank where the customer's account is held. Example: 123 Maple Street, London

bank_code   string   

The code that uniquely identifies the bank. Example: 0100

account_number   string   

The bank account number that uniquely identifies the customer's bank account. Example: 789456123

iban   string   

An international standard account number (IBAN) used to uniquely identify the customer's bank account for cross-border transactions. Example: GB23MBTC60161331926819

bic   string   

An international standard code (BIC/SWIFT) used to identify the customer's bank for cross-border transactions. Example: MBTCPHMMXXX

account_type   string   

The type of the bank account. Example: current

bank_clearing_system_code   string   

The bank clearing code (ISO 20022). Example: SGIBG

bank_clearing_system_id   string   

The bank clearing identifier (ISO 20022). Example: 1234567

fees  Fee    

Contains details about any fees associated with the transaction. This object includes information such as the name, type, amount, and currency of the fee.

name   string   

The name of the fee. Example: Service Fee

type   string   

The type of the fee, indicating its purpose or category. Example: "processing"

amount   string   

The amount of the fee. Example: "50.00"

currency   string   

The currency in which the fee amount is denominated. Example: "USD"

meta   Object   

Additional metadata related to the transaction, if available. Example: null


Gateways

Below is an overview of available gateways. For card types, you can use their testing cards linked in the table below. For each gateway, you can check the decline codes and see available endpoints. For wire and crypto gateways, testing often requires individual arrangements, so please contact us before testing, but testing is definitely an option before going live.

Gateway API Key Type Available Endpoints Required customer data Testing cards Decline Codes
Unlimit "unlimit" card Purchase, Refund first name, last name, email Testing Cards Decline Codes
TrustPay "trustpay" card Purchase, Refund, Reverse first name, last name, email Testing Cards Decline Codes
EmerchantPay "emerchantpay" card Purchase, Refund, Reverse first name, last name, email Testing Cards Decline Codes
Payabl "payabl" card Purchase, Refund first name, last name, email Testing Cards Decline Codes
Stripe "stripe" card Purchase, Refund first name, last name, email Testing Cards Decline Codes
VirtualPay "virtualpay" card Purchase first name, last name, email, phone, city, post code, country Testing Cards
Curfex "curfex" card Purchase first name, last name, email
Checkout "checkout" card Purchase, Refund first name, last name, email Testing Cards Decline Codes
Confirmo "confirmo" crypto Purchase first name, last name, email Real transactions
Maxconnect "maxconnect" wire Purchase first name, last name, email, phone Manual approval
BillPay "billpay" wire Purchase first name, last name, email, phone Manual approval
Skrill "skrill" wallet Purchase first name, last name, email Real transactions
Neteller "neteller" wallet Purchase first name, last name, email Real transactions
Unlimit APM "unlimit_apm" wallet Purchase, Refund [Depends on the selected Gateway] first name, last name, email Sandbox approval
Unlimit ShopeePay "unlimit_shopeepay" wallet Purchase, Refund first name, last name, email Sandbox approval
Inpay "inpay" wire Withdraw first name, last name, email Manual approval

Decline Codes

The following table lists the decline codes for card payments that our API may return.

Decline Code Description
GENERAL General decline
CARD_DATA Declines caused by incorrect or invalid card details β€” such as wrong number, expiry date, CVV, or use of an expired card.
CARD_LIMIT Triggered when the card hits transaction or usage limits.
RISK_FRAUD Blocked due to fraud or risk rules, including blacklists, suspicious patterns, or velocity checks.
3DS Related to 3D Secure authentication failures or technical errors in the 3DS flow.
INSUFFICIENT_FUNDS Declines due to the customer not having enough available funds or credit to complete the transaction.

iFrame

Instructions for Loading the Payment Page in an iFrame

To display the payment page within an iFrame, use a separate route specifically designed for this purpose, append iframe to the end of the redirect_url.

Example: https://secure.staging.paypipes.net/v2/redirect/d40828f0-b2ab-4fe1-9397-d6d45cc4b9bf/iframe


After the payment process is complete, we will trigger a redirect from the iframe by sending a message to the parent window.

window.parent.postMessage({ type: 'redirect', url: 'https://paypipes.com' }, '*');

Handle the Redirect on the Host Page:

On the host page, listen for the message event and check if the message type is 'redirect'

window.addEventListener('message', (event) => {
    if (event.data.type === 'redirect' && event.data.url) {
        window.location.href = event.data.url;
    }
});

Error Codes

The following table lists the error codes that our API may return, along with their corresponding descriptions.

Code Error
100000 GENERAL_ERROR
100001 UNAUTHENTICATED
100002 JSON_ENCODE_FAILED
100003 GENERAL_VALIDATION_ERROR
100004 UNAUTHORIZED
100005 URL_NOT_FOUND
100006 TOKEN_MISMATCH
100007 HTTP_EXCEPTION
100008 OAUTH_EXCEPTION
200000 REQUEST_FAILED
200001 SETUP_FAILED
200002 GATEWAY_NOT_FOUND
200003 CONFIGURATION_NOT_FOUND
200004 VALIDATOR_NOT_FOUND
200005 CLIENT_NOT_FOUND
200006 CREDENTIAL_NOT_FOUND
200007 MODEL_NOT_FOUND
200008 METHOD_NOT_FOUND
200009 TRANSACTION_NOT_FOUND
200010 TRANSACTION_CREATION_FAILED
200011 INVALID_GATEWAY
200012 INVALID_SETTINGS
200013 INVALID_STATUS
200014 INVALID_PAYMENT
200015 INVALID_WITHDRAW
200016 INVALID_REFUND
200017 INVALID_REVERSAL
200018 BANK_ACCOUNT_NOT_FOUND
200019 COLLECTORS_GATEWAY_NOT_FOUND
200020 INVALID_CURRENCY
200021 INVALID_AMOUNT
200022 INVALID_AMOUNT_FORMAT
200023 PAYMENT_ALREADY_PROCESSED
200024 INVALID_SIGNATURE
200025 WEBHOOK_URL_NOT_FOUND
200026 NOT_ELIGIBLE_FOR_WEBHOOK
200027 INVALID_WEBHOOK_SIGNATURE
200028 OPERATION_HANDLER_NOT_FOUND
200029 EMAIL_BLACKLISTED
200030 IP_BLACKLISTED
200031 COUNTRY_BLACKLISTED
200032 INVALID_TRANSACTION_CUSTOMER
200033 INVALID_CASCADING_GATEWAY
200034 INVALID_CASCADING_TRANSACTION
200035 INVALID_CASCADING_APPLE_PAY
200036 INVALID_TRANSACTION_STATUS
200037 TRANSACTION_EXPIRED
200038 TRANSACTION_GATEWAY_NOT_SET
200039 DEPOSIT_HANDLER_NOT_FOUND
200040 GATEWAY_NOT_SUPPORT
200044 TOKEN_CUSTOMER_LOAD_FAILED
200045 TRANSACTION_RETURN_URL_NOT_FOUND
200046 GET_STATUS_FAILED
200047 EMPTY_RETURN_URL
200048 REFUND_FAILED
200049 REVERSAL_FAILED
200050 MISSING_TOKEN_FOR_CURRENCY
200051 THREED_FAILED
200052 THREED_INVALID_DATA
200053 THREED_INVALID_SIGNATURE
200054 GATEWAY_TYPE_NOT_SET
200055 NOT_IMPLEMENTED
200056 CARD_NOT_RECOGNIZED
200057 CARBON_CREATE_FAILED
200058 CARD_BLACKLISTED
200059 CRYPTO_KEY_CREATION_FAILED
200060 CRYPTO_KEY_DECRYPTION_FAILED
200061 INVALID_TRANSACTION_TYPE
200062 INVALID_ACCESS_TOKEN
200063 INVALID_WALLET_ID
200064 INVALID_WALLET_SECRET
200065 INVALID_CALLBACK_SECRET
200066 INVALID_RESULT_STATUS
200067 INVALID_CALLBACK_PAYLOAD
200068 TRANSACTION_REFERENCE_NOT_FOUND
200069 NO_ROUTABLE_GATEWAYS
200070 FETCH_EXCHANGE_RATES_EXCEPTION
200071 NVP_TO_ARRAY_CONVERSION_FAILED
200072 XML_TO_ARRAY_CONVERSION_FAILED
200073 INVALID_TERMINAL
200074 INVALID_PARENT
200075 CUSTOMER_NOT_FOUND
200076 PARENT_TRANSACTION_NOT_FOUND
200077 INVALID_SESSION_IDENTIFIER
200078 INVALID_PHONE
200079 INVALID_ADDRESS
200080 ENCRYPTION_FAILED
200081 DECRYPTION_FAILED
200090 INVALID_GATEWAY_TYPE
200082 INVALID_SIMULATOR_TRANSACTION
200083 INVALID_MEMBER_ID
200084 MISSING_GATEWAY_TOKEN
200085 CARD_BRAND_NOT_SUPPORTED

WooCommerce Plugin

WooCommerce Plugin


Changelog

Here you can see the history of changes to this documentation:

Date Change
2025-06-19 Optional 'legal_entity' field of ENUM type (PRIVATE, BUSINESS) added to tokenize customer API endpoint.
2025-06-12 Added optional 'bank_clearing_system_code' field for tokenize bank API endpoint. If the field isn't empty then it's validated for bank clearing code (ISO 20022).
2025-06-12 Added optional 'bank_clearing_system_id' field for tokenize bank API endpoint. If the field 'bank_clearing_system_code' isn't empty then it's validated for bank clearing system ID (ISO 20022).
2025-04-11 Added optional 'date_of_birth' field for tokenize customer endpoint.
2024-11-20 Added simulator parameter for purchase endpoint to enable simulated payments.
2024-11-19 Enhanced the documentation by including instructions for the newly available gateways.
2024-06-01 Release