Skip to main content
API docs by Redocly

API Reference (v3)

Download OpenAPI specification:Download

Test

https://api.test.cyberpay.link

Production

https://api.cyberpay.link

Overview

The CyberPay API allows merchants to accept payments using popular payment methods in countries around the world.

This API is designed using REST, and supports Hosted and Direct integrations:

  • Hosted Cashier: Our quick-to-integrate approach provides you with a hosted cashier UI. An easy solution for the merchant’s customers to initiate and complete payments using their preferred payment options from different countries.
  • Direct integration using API only: Use our API and your own UI.
  • Webhook: Information about the webhook system.

Error Codes

Error Code Status Error Reason Description
1000 DECLINED Validation error. Default validation error.
1001 DECLINED Missing phone number. Customer phone number is missing.
1002 DECLINED Invalid document id. Document ID is not accepted by the provider.
1003 DECLINED Invalid document type. Document type is not accepted by the provider.
1004 DECLINED Invalid phone number. Phone number is incorrect.
1005 DECLINED Invalid bank account format. Bank account format is invalid.
1006 DECLINED Invalid zip code. Zip code format is invalid or missing.
1007 DECLINED Payment amount is too low. Payment amount is too low.
1008 DECLINED Payment amount is too high. High amount received.
1009 DECLINED Invalid amount. Invalid payment amount, wrong format perhaps?
1010 DECLINED Payment option is not allowed. The selected payment option is not enabled for the brand.
1011 DECLINED Selected payment option is not allowed in this country.
1012 DECLINED Selected payment option is not allowed for this currency.
1013 DECLINED Payment amount is too low for this payment option.
1014 DECLINED Payment amount is too high for this payment option.
1100 ERROR Contact support to confirm payment. Contact support to confirm payment.
3000 DECLINED Insufficient card funds. Card doesn't have enough funds to complete the transaction.
3001 DECLINED Do not honour.
3002 DECLINED Untrusted transaction. Risk decline.
3003 DECLINED Abandoned 3DS.
3004 DECLINED Invalid CVV2/CVC2.
3005 DECLINED Invalid cardholder name. Cardholder name wasn't accepted.
3006 DECLINED Exceeded amount limit.
3007 DECLINED Card expired. An expired card was used.
3008 DECLINED Transaction already in progress. A transaction is already in progress.
3009 DECLINED Invalid card number.
3010 DECLINED Customer has failed 3DS. 3DS was abandoned by customer.
3011 DECLINED No card record.
3012 DECLINED Pickup card.
3013 DECLINED Charge count limit reached for this card.
3014 DECLINED Exceeded amount limit.
3015 DECLINED Transaction not permitted to cardholder.
3016 DECLINED Visa decline. The transaction was declined by the card scheme (Visa).
3017 DECLINED Duplicate transaction.
3018 DECLINED Payment was not received.
3019 DECLINED Recalculation.
3020 DECLINED Transaction amount less than allowed.
3021 DECLINED Country is blocked.
3022 DECLINED Transaction blocked. Generic blocked transaction.
3023 DECLINED Declined by card Issuer. VSIFC
3024 DECLINED Card type declined. This type of card is blocked.
3025 DECLINED Transaction not allowed in country. Only a local card can be used.
3026 DECLINED Mastercard Decline. The transaction was declined by the card scheme (Mastercard).
3027 DECLINED Acquirer side error. Acquirer side error.
3028 DECLINED Card not enrolled to 3D. Card not enrolled to 3D.
3029 DECLINED Authentication Rejected Card Authentication Rejected
3030 DECLINED Previous Transaction already in progress. Previous Transaction already in progress
3031 DECLINED Restricted card.
3032 DECLINED Suspected fraud.
3033 DECLINED This Transaction was Declined by Scheme (Visa) Card-scheme decline.
3034 DECLINED Previous Transaction already in progress A previous transaction is still in progress.
3035 DECLINED Invalid card expiry date The card expiry date is invalid.
3045 DECLINED Risk Engine Decline Declined by the risk engine.
991 DECLINED Acquirer timeout. The acquirer did not respond within the allowed time.
992 DECLINED Blacklisted IP.
993 DECLINED Customer blacklisted.
994 DECLINED Unidentified subject. Blacklisted card.
995 DECLINED No payment options were found. No payment options were found for the payment.
996 DECLINED Currency conversion error. Could not convert currency.
997 DECLINED No route was found. Couldn't route payment to any provider.
998 DECLINED Adapter timeout. Communication error with our adapter.
999 DECLINED Miscellaneous error. Default error for unmapped errors.

Payin

Get Hosted Cashier link

Initiate a payment session and receive a link to the Hosted Cashier UI.

Session lifetime depends on the environment's configuration. Contact CyberPay for the timeout used by your integration. Only one payment is allowed per session. Redirect the customer to the exact cashierUrl returned; do not construct this URL yourself.

Send X-Signature when body-signature enforcement is enabled for your brand. Successful responses include X-Signature. See Signatures.

Authorizations:
Authorization
header Parameters
X-Signature
string

Required when body-signature enforcement is enabled for the brand. Base64 HMAC-SHA256 of the JSON-serialized request body using the brand signature key.

Request Body schema: application/json
required

This endpoint will generate a payment session. The Hosted Cashier will display available payment options based on the given country/currency/amount parameters.

Supply the customer details available to your integration. Additional information may be collected in the cashier.

country
required
string

ISO alpha-2 country code

currency
required
string

ISO currency code

amount
number

Optional payment amount. Fiat currencies allow at most two decimal places; supported cryptocurrencies allow at most eight.

redirectUrl
required
string

Merchant redirect page after payment.

notificationUrl
string

Merchant notification webhook URL. This value overrides the notification URL configured in the merchant portal.

language
string

ISO alpha-2 language code

required
object non-empty

A non-empty customer object is required. Individual fields are optional at request validation; the selected method may require additional details in the cashier. Use name for the full name, rather than the split-name fields used by v3.

merchantReference
string <= 255 characters

Your unique payment reference. Generated when omitted.

merchantDomain
string <= 255 characters

Required for payment-facilitator brands. Must exactly match a domain configured for the brand.

paymentReference
string

Reference to be used for the payment.

userId
string

User identifier on the merchant system.

extra1
string

Optional merchant metadata for tracking the payment.

extra2
string

Optional merchant metadata for tracking the payment.

extra3
string

Optional merchant metadata for tracking the payment.

storedToken
string

Stored payment credential.

tax
string

Tax percentage.

object

Shipping address object.

Array of objects

Array of product details.

Responses

Request samples

Content type
application/json
{
  • "country": "BR",
  • "currency": "BRL",
  • "amount": 130,
  • "redirectUrl": "https://merchant.io/where-to-go",
  • "language": "ES",
  • "customer": {
    },
  • "paymentReference": "Invoice ABC123",
  • "userId": "Merch_User_123",
  • "extra1": "extraData001",
  • "extra2": "extraData002",
  • "extra3": "extraData003",
  • "storedToken": "index-stored",
  • "tax": "21%",
  • "shippingAddress": {
    },
  • "orderDetails": [
    ]
}

Response samples

Content type
application/json
{}

Payout

Get Hosted Cashier link

Initiate a payout session and receive a link to the Hosted Cashier UI.

Session lifetime depends on the environment's configuration. Contact CyberPay for the timeout used by your integration. Only one payout is allowed per session. Redirect the customer to the exact cashierUrl returned; do not construct this URL yourself.

Send X-Signature when body-signature enforcement is enabled for your brand. Successful responses include X-Signature. See Signatures.

Authorizations:
Authorization
header Parameters
X-Signature
string

Required when body-signature enforcement is enabled for the brand. Base64 HMAC-SHA256 of the JSON-serialized request body using the brand signature key.

Request Body schema: application/json
required

This endpoint will generate a payout session. The Hosted Cashier will display available payout options based on the given country/currency/amount parameters.

country
required
string

ISO alpha-2 country code.

currency
required
string

ISO alpha-3 currency code.

amount
required
number decimal places <= 2

Required payout amount, with at most two decimal places for every currency.

redirectUrl
required
string

Merchant page to redirect the customer to after the payout.

notificationUrl
string

Merchant notification webhook URL. This value overrides the notification URL configured in the merchant portal.

required
object

Recipient details used to prepare the payout.

merchantReference
string

Your unique payout reference. Generated when omitted.

merchantDomain
string

Required for payment-facilitator brands. Must exactly match a domain configured for the brand.

userId
string

User ID generated by the merchant system.

language
string

ISO alpha-2 language code. Values: ‘EN’, ‘ES’, ‘PT’, ‘IN’.

extra1
string

Optional payload to help the merchant track this payout.

extra2
string

Optional payload to help the merchant track this payout.

extra3
string

Optional payload to help the merchant track this payout.

Responses

Request samples

Content type
application/json
{
  • "country": "BR",
  • "currency": "BRL",
  • "amount": 150,
  • "redirectUrl": "https://merchant1.io/where/to/go",
  • "customer": {
    },
  • "userId": "merchant_user123",
  • "language": "PT",
  • "extra1": "merchant extra value 1",
  • "extra2": "merchant extra value 2",
  • "extra3": "merchant extra value 3"
}

Response samples

Content type
application/json
{}

Payin (v3)

Get Payment Options (Optional)

Get available payment options enabled for your merchant. The request can be filtered by country and currency. This optional call does not create a session. See the v3 pay-in guide.

Authorizations:
Authorization
query Parameters
country
string^[A-Za-z]{2}$
Example: country=DE

Optional two-letter country code.

currency
string
Example: currency=EUR

Optional ISO 4217 currency code.

excludeCountries
boolean
Default: false

Set to true to return empty availableCountries arrays.

Responses

Response samples

Content type
application/json
Example
[
  • {
    }
]

Submit Payment

Create a pay-in. See the complete v3 integration guide for card and APM examples, required fields, customer actions, and webhook handling.

Requests must first pass validation. Card payments require a non-empty paymentData object with valid card details or a saved card token. Missing or invalid card data can return HTTP 400 before a transaction is created. After validation, missing country, customer, or method-specific information can trigger a Hosted Cashier redirect.

Note: 3D Secure authentication for card payments uses a redirect URL. The destination page may contain an iframe, so opening it inside another iframe may cause issues.

Authorizations:
Authorization
header Parameters
X-API-KEY
required
string
Example: 52495b8782698e9d0309897795aa24ad20a63710f54d9d244d7523a6e17bdeba0da13c72a282fd88e545f502b2fae9ae

Your merchant API key.

Idempotency-Key
string
Example: 7ad6249c-b1eb-434f-83db-e42676ea3e28

Card payments only. A key of up to 64 characters can replay a stored response for the same merchant and brand. Records expire after 48 hours. Early cashier redirects and in-flight requests may not have a stored response; reconcile before retrying. See the retry guidance.

Signature
string
Example: QGrW5AgToyf6wytINIdNVHiNwIHP9PvHIirGwgr88Jc=

Card payments only. Base64-encoded HMAC-SHA256 signature, required when signature enforcement is enabled for the brand. The string to sign must match this format paymentOptionId:merchantReference:currency:amount and must be signed with the signature key provided for your merchant. Example payloads 4864ab16-2fa4-464a-b692-a74cab45aaf8::EUR:50.32, 4864ab16-2fa4-464a-b692-a74cab45aaf8:reference04322:USD:1000

Note: Signature enforcement can be enabled for your brand.

Request Body schema: application/json
paymentOptionId
required
string <uuid>

Selected payment option ID. For example, 4864ab16-2fa4-464a-b692-a74cab45aaf8 for cards. The list of available payment options can be retrieved by using the Get Payment Options endpoint.

country
string = 2 characters

ISO alpha-2 country code. Set this if possible; otherwise, the customer will be redirected to the cashier to choose from a dropdown.

currency
required
string = 3 characters

ISO 4217 currency code supported by the selected method.

amount
required
number >= 0

Decimal value allowing at most two digits after the decimal point.

redirectUrl
string <= 500 characters

Merchant page to redirect the customer to after the payment.

notificationUrl
string <= 500 characters

Merchant notification webhook URL. This value overrides the notification URL configured in the merchant portal.

language
string = 2 characters

ISO alpha-2 language code. Values: EN, ES, PT, AR, IN.

object

Required and non-empty for cards; send valid card details or a saved token as described in the pay-in guide. Optional at request validation for non-card methods. Field names and processing requirements depend on the selected method.

object

Customer object with end-user details. Some user data is needed in almost all cases. Provide as much data as possible; otherwise, the customer will be redirected to the cashier to fill in the missing details.

merchantDomain
string <= 255 characters

Required for payment-facilitator brands. Must exactly match a domain configured for the brand.

merchantReference
string [ 1 .. 255 ] characters

Merchant reference. Must be unique. If omitted, CyberPay generates one.

paymentReference
string [ 1 .. 255 ] characters

Reference to be used for the payment. If omitted, CyberPay generates one.

userId
string [ 1 .. 255 ] characters

User ID in the merchant system.

extra1
string [ 1 .. 255 ] characters

Optional parameter to track this payment.

extra2
string [ 1 .. 255 ] characters

Optional parameter to track this payment.

extra3
string [ 1 .. 255 ] characters

Optional parameter to track this payment.

object

Shipping address data.

Array of objects

Optional product details, such as quantity, dimensions, and description. Refer to the Useful Data section for more information.

Responses

Request samples

Content type
application/json
Example

Full data object

{
  • "paymentOptionId": "4864ab16-2fa4-464a-b692-a74cab45aaf8",
  • "country": "GB",
  • "currency": "GBP",
  • "amount": 50.32,
  • "redirectUrl": "https://merchant.io/redirect-back",
  • "notificationUrl": "https://merchant.io/webhook/mr-439238347213",
  • "paymentData": {
    },
  • "customer": {
    },
  • "language": "EN",
  • "paymentReference": "Invoice ABC123",
  • "merchantReference": "mr-439238347213",
  • "userId": "Merch_User_123",
  • "extra1": "extraData001",
  • "extra2": "extraData002",
  • "extra3": "extraData003",
  • "shippingAddress": {
    },
  • "orderDetails": [
    ]
}

Response samples

Content type
application/json
Example

Payment was completed. No further action is needed.

{
  • "statusCode": 200,
  • "resultType": "success",
  • "result": {
    }
}

Confirm Payment When Required

Submit a receipt or additional confirmation for a supported payment method. Use the sessionId returned by the payment response. This is not a general approval step for pay-ins.

The required confirmation values depend on the method. Send JSON for text-only confirmation, or multipart/form-data when uploading a receipt. A receipt image or PDF must be smaller than 2 MB.

When body-signature enforcement is enabled for the brand, send X-Signature using the JSON-serialized body fields. For multipart requests, exclude the uploaded file bytes. Responses include X-Signature using the JSON-serialized response body.

A successful confirmation submission does not prove the payment completed. Follow the pay-in integration guide and await the final transaction status.

Authorizations:
Authorization
header Parameters
X-Signature
string

Required when body-signature enforcement is enabled. Base64 HMAC-SHA256 of the JSON-serialized body fields using the signature key.

Request Body schema:
required
sessionId
required
string <uuid>

Session ID returned by the payment response.

essentialKey
string [ 1 .. 255 ] characters

Confirmation value required by the selected method.

additionalEssentialKey
string [ 1 .. 255 ] characters

Additional reference required by the method. Supported UPI confirmation without a receipt requires a 12-digit UTR/RRN.

Responses

Request samples

Content type
{
  • "sessionId": "dfa27e08-e6e4-4d87-8ca3-216445f11864",
  • "essentialKey": "+201001234565"
}

Response samples

Content type
application/json
Example
{
  • "message": "Your payment has been sent."
}

Payout (v3)

1. List Payout Options

List payout methods enabled for your brand. This optional discovery call does not create a transaction or session.

Use an option's id as paymentOptionId when creating a payout. To select a specific bank or other suboption, use its suboptions[].id instead.

The response is an array, which can be empty. It does not include payout form fields or amount limits. Availability for the requested amount and required recipient details are checked when you submit the payout.

See the v3 payout integration guide.

Authorizations:
Authorization
query Parameters
country
string^[A-Za-z]{2}$
Example: country=BR

Optional two-letter country code. Case-insensitive.

currency
string
Example: currency=BRL

Optional ISO 4217 currency code.

excludeCountries
boolean
Default: false

Set to true to return an empty availableCountries array for each option.

Responses

Response samples

Content type
application/json
Example
[
  • {
    }
]

2. Create Payout

Create a payout in one request using a payout option or suboption ID. No preceding session-creation call is required.

paymentOptionId, currency, and amount are required. Provide country, customer, and the selected method's paymentData to avoid unnecessary data-collection steps. Required recipient fields depend on the method, country, provider, and brand configuration.

If country, bank selection, or required data is missing, the response can contain a cashier redirectUrl. Redirect the customer to that URL and follow the existing transaction through webhooks or transaction queries.

HTTP 201 means the request returned a business result. Inspect the numeric body statusCode, resultType, and result.status:

statusCode resultType result.status Next step
200 success PENDING Approve or decline in the merchant portal or with POST /settle-payout.
200 success PROCESSING Auto-approval submitted the payout. Await the final status.
300 redirect PROCESSING Redirect the customer to result.redirectUrl.
900 declined DECLINED Inspect result.errorCode and result.errorReason.
999 error DECLINED Submission failed during auto-approval; inspect the error and transaction status.

success does not confirm that funds have reached the recipient. Use webhooks or query the transaction for its final status.

Use a unique merchantReference per payout. This endpoint does not implement Idempotency-Key replay: after a timeout, reconcile the existing transaction before submitting again.

Authorizations:
Authorization
Request Body schema: application/json
required
paymentOptionId
required
string <uuid>

An option ID or suboptions[].id returned by GET /v3/payout-options.

country
string^[A-Za-z]{2}$

Two-letter country code. Omission can trigger a cashier country-selection redirect.

currency
required
string

ISO 4217 currency code supported by the selected payout method.

amount
required
number >= 0

Payout amount in the requested currency. Fiat amounts allow at most two decimal places. The method's minimum and maximum limits also apply.

object

Method-specific recipient or bank details. Field names and requirements depend on the configured payout method and provider; the options endpoint does not return a form schema. Missing required data can trigger a cashier redirect.

object (V3PayoutCustomer)

Customer details are optional at request validation, but the selected method or brand can require them to process the payout.

redirectUrl
string <= 500 characters

Merchant return URL after the customer finishes the cashier flow. A browser return does not confirm payout completion.

notificationUrl
string <= 500 characters

HTTPS webhook endpoint. Overrides the brand's configured notification URL for this payout.

merchantReference
string <= 255 characters

Your unique payout reference, recommended for reconciliation. Generated when omitted. A duplicate reference for the same merchant and country is rejected; this is not an idempotency replay mechanism.

paymentReference
string <= 255 characters

Payment reference. Generated when omitted.

userId
string <= 255 characters

Your stable customer ID. Generated when omitted. Existing customer profile data may be used to fill missing details.

language
string^[A-Za-z]{2}$

Two-letter cashier language code.

merchantDomain
string

Required for payment-facilitator brands. Must exactly match a domain configured for the brand.

extra1
string <= 255 characters

Additional merchant information.

extra2
string <= 255 characters

Additional merchant information.

extra3
string <= 255 characters

Additional merchant information.

Responses

Request samples

Content type
application/json
Example
{
  • "paymentOptionId": "4864ab16-2fa4-464a-b692-a74cab45aaf8",
  • "currency": "BRL",
  • "amount": 100
}

Response samples

Content type
application/json
Example
{
  • "statusCode": 200,
  • "resultType": "success",
  • "result": {
    }
}

3. Approve or Decline Payout

Approve or decline an existing payout in PENDING status. You can also do this in the merchant portal. This step is needed when automatic payout approval is disabled for the brand.

APPROVE submits the payout to the provider, subject to provider availability and sufficient merchant balance. It can still be declined. DECLINE marks the transaction as declined without sending funds.

This unversioned endpoint retains its legacy response format: string statusCode, top-level status, and string result. It does not return the v3 resultType envelope.

The current response to an intentional DECLINE uses statusCode: "999", status: "DECLINED", and result: "Could not process payout.". This also represents a successful merchant rejection; inspect the transaction status rather than retrying the request.

Send X-Signature when body-signature enforcement is enabled for your brand. The response includes X-Signature. See signatures.

Authorizations:
Authorization
header Parameters
X-Signature
string

Required when body-signature enforcement is enabled. Base64 HMAC-SHA256 of the JSON-serialized body using the signature key.

Request Body schema: application/json
required
action
required
string
Enum: "APPROVE" "DECLINE"
transactionId
required
string <uuid>

The result.transactionId returned by POST /v3/payout.

Responses

Request samples

Content type
application/json
Example
{
  • "action": "APPROVE",
  • "transactionId": "f6ab9d53-db1e-4cd9-bafa-a8e31247054d"
}

Response samples

Content type
application/json
Example
{
  • "statusCode": "000",
  • "status": "PROCESSING",
  • "transactionId": "f6ab9d53-db1e-4cd9-bafa-a8e31247054d",
  • "merchantReference": "withdrawal-2026-0001",
  • "result": "Payout settle was submitted successfully."
}

Refunds

Refund by Reference

Refund a completed payment to its original account using your merchantReference. The transaction must have status COMPLETED, its provider must support refunds, and its payment method must allow them. This endpoint requests a full refund; an authorization alone is not sufficient.

Send X-Signature when body-signature enforcement is enabled for your brand. Successful responses include X-Signature. See Signatures.

Authorizations:
Authorization
header Parameters
X-Signature
string

Required when body-signature enforcement is enabled for the brand. Base64 HMAC-SHA256 of the JSON-serialized request body using the brand signature key.

Request Body schema: application/json
required
merchantReference
required
string

Reference submitted for the original payment.

Responses

Request samples

Content type
application/json
{
  • "merchantReference": "order-2026-0001"
}

Response samples

Content type
application/json
{
  • "transactionId": "feb6a715-9f7c-49d4-b6f7-10c59d18a194",
  • "status": "REFUNDED",
  • "partialRefund": false,
  • "paymentAmount": 50.32,
  • "currency": "EUR",
  • "country": "DE",
  • "type": "CARD",
  • "merchantReference": "order-2026-0001",
  • "createdAt": "2026-09-01T10:00:00.000Z",
  • "updatedAt": "2026-09-01T10:05:00.000Z"
}

Query Transactions

Get Transaction Status

Get transaction details

Return all details about the transaction by a given transaction ID.

Authorizations:
Authorization
path Parameters
transactionId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "099cdc76-45d1-49e1-8985-e1c82dcfadb3",
  • "sessionId": "90545ca3-fe0d-457c-a9da-283ee2561d82",
  • "country": "GB",
  • "currency": "GBP",
  • "paymentAmount": 10,
  • "originalCurrency": "GBP",
  • "originalAmount": 10,
  • "method": "Bank Transfer",
  • "status": "COMPLETED",
  • "paymentReference": "invoice-4726",
  • "merchantReference": "Merchant Unique Value",
  • "customer": {
    },
  • "shippingAddress": {
    },
  • "orderDetails": [
    ],
  • "errors": null,
  • "createdAt": "2022-08-04T08:23:50.738Z",
  • "updatedAt": "2022-08-05T08:23:50.738Z"
}