Developer documentation

Overview

General information required for every request to the Paysation Payment Gateway API.

Base URLs

Paysation does not use a separate staging URL. The API endpoint is the same for both test and live. See Test API.

Required headers

Every request must include the following HTTP headers:

Example

POST /<endpoint> HTTP/1.1
Host: api.paysation.com
Content-Type: application/json
Authorization: Bearer %API KEY%

{
  "...": "..."
}

Response format

All responses are returned as JSON encoded in UTF-8. See all possible HTTP response codes in Response codes.

The HTTP status reflects the outcome of the call:

Error response example

Any response with status >= 400 contains a message field with a human-readable explanation:

1{
2  "message": "Invalid request payload"
3}

Notes

Test API

This page describes how to simulate payment scenarios before going live.

Test environment overview

Paysation does not use a separate staging URL. The API endpoint is the same for both test and live:

https://api.paysation.com

To access the test environment, each client is provisioned with a dedicated set of test resources:

Test credentials and live credentials are completely isolated — a request made with test credentials never affects live funds or live transaction history.

Test cards do not process real funds and work only when authenticated with test credentials.

General rules

Test cards

Decline scenario

Sale

Direct card charge without 3DS authentication. The merchant sends card data server-to-server; the gateway processes the payment and returns the final result.

To split authorization and capture, set capture to false in the request — funds are only authorized. The merchant then calls /settle to capture, or /void to release the hold.

Endpoint

Base URLs and required headers (Content-Type, Authorization) are defined in Overview.

Request body

Top-level fields:

paymentMethod

The object contains exactly one key, which identifies the payment method type. Supported keys: card / token / applePay / googlePay. This document describes the card method.

card

customer

Request example

1{
2  "clientTransactionId": "order_20260512_0091",
3  "amount": 49.99,
4  "currency": "USD",
5  "description": "Premium subscription — 1 month",
6  "paymentMethod": {
7    "card": {
8      "number": "4111111111111111",
9      "securityCode": "737",
10      "expMonth": "09",
11      "expYear": "28",
12      "cardHolderName": "John Doe"
13    }
14  },
15  "customer": {
16    "firstName": "John",
17    "lastName": "Doe",
18    "address": "742 Evergreen Terrace",
19    "city": "Springfield",
20    "country": "US",
21    "zipcode": "90210",
22    "state": "IL",
23    "phone": "14155552671",
24    "ipAddress": "203.0.113.42",
25    "email": "[email protected]"
26  },
27  "webhookUrl": "https://merchant.example.com/webhooks/payment"
28}

Response

HTTP status codes and the error response shape are defined in Overview — Response format.

The response body contains the following fields:

Example — success

1{
2  "status": "success",
3  "transactionId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
4  "clientTransactionId": "order_20260512_0091",
5  "schemeTransactionId": "012345678901234",
6  "paymentToken": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
7  "code": "00",
8  "message": "Approved"
9}

Payment failed:

1{
2  "status": "failed",
3  "transactionId": "3c2b1a4e-5d6f-7e8a-9b0c-1d2e3f4a5b6c",
4  "clientTransactionId": "order_20260512_0091",
5  "schemeTransactionId": "998877665544332",
6  "code": "11",
7  "message": "Insufficient funds",
8  "bankDeclineCode": "51"
9}

3D Server-to-Server

Card charge with 3DS authentication. The merchant sends a card data server-to-server. The gateway returns a redirectUrl to which the customer must be redirected to complete 3DS. After authentication, the final status is delivered to:

1. The redirectUrl provided in the request (browser return). 2. The webhookUrl provided in the request (asynchronous server-to-server notification).

The request is identical to Sale with the following additions: 3ds, browserDetails and redirectUrl.

Endpoint

Base URLs and required headers (Content-Type, Authorization) are defined in Overview.

Request body

Top-level fields:

Nested objects (paymentMethod, customer) have the same fields and constraints as in Sale.

browserDetails

Collected on the merchant checkout page from the customer browser and passed to the gateway. Field semantics follow the EMV 3DS 2.x specification.

Request example

1{
2  "clientTransactionId": "order_20260512_0092",
3  "amount": 49.99,
4  "currency": "USD",
5  "description": "Premium subscription — 1 month",
6  "3ds": true,
7  "paymentMethod": {
8    "card": {
9      "number": "4111111111111111",
10      "securityCode": "737",
11      "expMonth": "09",
12      "expYear": "28",
13      "cardHolderName": "John Doe"
14    }
15  },
16  "customer": {
17    "firstName": "John",
18    "lastName": "Doe",
19    "address": "742 Evergreen Terrace",
20    "city": "Springfield",
21    "country": "US",
22    "zipcode": "90210",
23    "state": "IL",
24    "phone": "14155552671",
25    "ipAddress": "203.0.113.42",
26    "email": "[email protected]"
27  },
28  "browserDetails": {
29    "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
30    "javaEnabled": false,
31    "jsEnabled": true,
32    "language": "en-US",
33    "colorDepth": 24,
34    "screenHeight": 1080,
35    "screenWidth": 1920,
36    "tzOffset": -120,
37    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0 Safari/537.36",
38    "challengeWindowSize": "03"
39  },
40  "redirectUrl": "https://merchant.example.com/checkout/return",
41  "webhookUrl": "https://merchant.example.com/webhooks/payment"
42}

Response

HTTP status codes and the error response shape are defined in Overview — Response format.

The response body contains the following fields:

threeDS fields

Example — initial response (fingerprint / challenge)

Returned immediately after the POST request when 3DS redirect is required. HTTP 202.

1{
2  "status": "pending",
3  "transactionId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
4  "clientTransactionId": "order_20260512_0092",
5  "threeDS": {
6    "threeDVersion": "2.2.0",
7    "flow": "fingerprint",
8    "redirectUrl": "https://3ds.paysation.com/fingerprint/9b1deb4d"
9  },
10  "code": "00",
11  "message": "3DS authentication required"
12}

Example — final result (frictionless, success)

Delivered via webhook and browser redirect. HTTP 201.

1{
2  "status": "success",
3  "transactionId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
4  "clientTransactionId": "order_20260512_0092",
5  "schemeTransactionId": "012345678901234",
6  "paymentToken": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
7  "threeDS": {
8    "threeDStatus": "Y",
9    "threeDVersion": "2.2.0",
10    "flow": "frictionless",
11    "authCode": "AUTH123456",
12    "eci": "05",
13    "cavv": "AAABBRRRSSSggghhh777AABBRRS=",
14    "acsChallenge": "N",
15    "liabilityShift": true
16  },
17  "code": "00",
18  "message": "Approved"
19}

After 3DS completion

Once the customer completes 3DS, the final payment result is delivered to both endpoints supplied in the request:

Recurring

How to charge a customer with a previously stored payment token — for subscription renewals, repeat purchases, and any payment against a stored credential.

Recurring does not have its own endpoint. It reuses Sale (POST /payment) with one difference: the paymentMethod object uses the token key instead of card. Card data (number, securityCode, expMonth, expYear, cardHolderName) is therefore not sent.

The caller must always indicate whether the charge is customer-initiated (cit) or merchant-initiated (mit) via recurringType — this value is required by the card networks (Visa Stored Credential Framework, Mastercard, EMV 3DS) for correct authorization and chargeback liability.

Endpoint

Same as Sale. Base URLs and required headers (Content-Type, Authorization) are defined in Overview.

Request body

Top-level fields are the same as in Sale — clientTransactionId, amount, currency, description, capture, customer, webhookUrl. Only the paymentMethod object differs.

In a recurring charge, customer is optional (overrides the Sale requirement). The cardholder is normally not present — especially for mit — and the gateway already has the customer data from the original Sale that produced the token.

paymentMethod

For a recurring charge, paymentMethod contains the single key token (instead of card).

token

recurringType values

Request example

1{
2  "clientTransactionId": "order_20260514_0114",
3  "amount": 49.99,
4  "currency": "USD",
5  "paymentMethod": {
6    "token": {
7      "paymentToken": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
8      "recurringType": "mit"
9    }
10  }
11}

Response

The response fields are identical to Sale — Response

The response body contains:

Example

1{
2  "status": "success",
3  "transactionId": "c2f4b8a1-9e3d-4f72-8c0b-5a1d2e6f0b91",
4  "clientTransactionId": "order_20260514_0114",
5  "schemeTransactionId": "012345678901234",
6  "paymentToken": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
7  "code": "00",
8  "message": "Approved"
9}

Payment failed:

1{
2  "status": "failed",
3  "transactionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
4  "clientTransactionId": "order_20260514_0114",
5  "schemeTransactionId": "554433221100998",
6  "code": "11",
7  "message": "Insufficient funds",
8  "bankDeclineCode": "51"
9}

Void / Settle

Follow-up operations on a previously authorized Sale. To enable this flow, the original Sale must be submitted with capture: false — funds are then only authorized (held), not captured.

The merchant uses the transactionId returned in the Sale response to:

Each call decides the final outcome of the authorization; only one of the two can be performed per transaction.

Base URLs and required headers (Content-Type, Authorization) are defined in Overview.

Authorization hold management

When submitting a Sale with capture: false, two behaviors are available depending on whether settleInterval is provided.

Manual settle

Omit settleInterval. The merchant decides when to settle by calling /settle, or cancels with /void.

If neither /settle nor /void is called before the card scheme hold limit expires, the gateway automatically sends a void to release the held funds.

Auto-settle

Pass settleInterval (in hours) in the original Sale request. The gateway will automatically submit the settle operation after the specified interval — no separate /settle call is needed.

If the auto-settle fails, the authorization hold remains active and the gateway will retry.

The merchant can still send /void or /settle at any time before settleInterval elapses.

Card scheme hold limits settleInterval cannot exceed the card scheme maximum. If the value is higher, the gateway clamps it to the scheme limit. | Card scheme | Maximum hold period | | --- | --- | | Visa (CIT) | 240 hours (10 days) | | Visa (MIT) | 120 hours (5 days) | | Mastercard and other schemes | 168 hours (7 days) |

Settle

Capture funds from an existing authorized transaction. Settle requests are submitted to the processor in a batch — the gateway returns status: pending immediately and delivers the final result via webhook.

Partial settle

If amount in the request is less than the authorized amount, only that portion is captured. The remaining hold is automatically voided by the gateway immediately after the capture succeeds. Only one settle per authorization is possible — to capture the remainder, use a separate Sale.

Refunds are limited to the settledAmount returned in the settle response.

Endpoint

Request body

Response

HTTP 201 is returned for all processed requests. Check status and code in the response body for the actual outcome. HTTP status codes and the error response shape are defined in Overview — Response format.

The response body contains:

status values

Void

Cancel an authorization created by a Sale with capture: false. No funds are transferred and the hold is released immediately.

Endpoint

Request body

Response

HTTP 201 is returned for all processed requests. Check status and code in the response body for the actual outcome. HTTP status codes and the error response shape are defined in Overview — Response format.

The response body contains:

status values

Refund

Return funds to the cardholder for a previously settled transaction — full or partial.

Base URLs and required headers (Content-Type, Authorization) are defined in Overview.

Endpoint

Partial refund

If amount in the request is less than the settled amount, only that portion is returned to the cardholder. Multiple partial refunds against the same transaction are allowed until the full settled amount is exhausted. To check how much remains refundable, use the transaction details endpoint.

Request body

Refund reason

Some processors and PSPs require a reason code on every refund request. The gateway handles this transparently: 1. Client provided reason — the gateway maps it to the processor-specific format and forwards it. 2. Client did not provide reason — the gateway substitutes a constant default value (OTHER or equivalent) that satisfies the processor's mandatory field requirement. The merchant does not need to be aware of which processors require it.

Accepted reason values

The following values are accepted in the reason field. They are normalized by the gateway and mapped to the correct format for each processor.

If reason is omitted or the processor does not accept reason codes, the gateway uses the processor's required default constant internally — no error is returned to the merchant.

Request example

1{
2  "clientTransactionId": "refund_20260516_0021",
3  "transactionId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
4  "amount": 19.99,
5  "reason": "customer_request"
6}

Response

The response fields are identical to Sale — Response.

The response body contains:

Example

1{
2  "status": "success",
3  "transactionId": "a5f8c2e1-1234-4cde-9876-fedcba987654",
4  "clientTransactionId": "refund_20260516_0021",
5  "refundedAmount": 19.99,
6  "refundedCurrency": "USD",
7  "code": "00",
8  "message": "Refund approved"
9}

Refund rejected:

1{
2  "status": "failed",
3  "transactionId": "b6a9d3f2-5678-4efg-1234-abcdef012345",
4  "clientTransactionId": "refund_20260516_0021",
5  "code": "51",
6  "message": "Refund not allowed: open dispute on this transaction"
7}

Constraints

Response codes

Reference for all codes returned by the Paysation API. Four independent surfaces:

1. HTTP status codes

All responses are returned as JSON encoded in UTF-8.

201 means the request reached the gateway and was processed. The actual payment outcome is always in the response body — check status and code. 202 is returned only when the customer must complete a 3DS step (fingerprint or challenge). It is never returned for other async operations.

2. status values

3. code and message values

All codes below are returned inside the JSON response body alongside code and message fields.

code: "00" indicates success and is returned alongside status: success.

The HTTP status that accompanies each code group is noted in each section header.

Success · HTTP 201

General issuer declines

Card validation

Transaction declines

Fraud and anti-fraud

3DS and authentication

Merchant configuration

Request validation · HTTP 400

Returned when the request body is structurally invalid — a required field is missing, a field value does not pass format validation, or the body is not valid JSON.

Token errors · HTTP 422

Returned when the token in the request is not usable. The request was valid but cannot be processed because the referenced token does not exist, has expired, or has already been consumed.

Transaction state · HTTP 422

Returned when the operation is structurally valid but the referenced transaction is in a state that does not permit the requested action.

Technical and connection · HTTP 500

Returned when a server-side or processor-side failure occurred. The request was valid and reached the gateway, but processing could not be completed due to an infrastructure or connectivity issue. Safe to retry after a short wait.

4. bankDeclineCode

Raw decline code passed through from the card scheme (Visa, Mastercard, American Express, Discover). Present only when the charge was submitted to the scheme and the issuer returned a decline code.

The meaning of the same numeric code differs by scheme. Always consider the card brand when interpreting this field. Use code and message for normalized, scheme-agnostic decline reasons.

Visa

Mastercard

American Express

Discover