Skip to main content
API docs by Redocly

API References (v3)

Download OpenAPI specification:Download

Test

https://api.test.cyberpay.link

Production

https://api.cyberpay.link

Overview

The Cyberpay API allow merchants to accept payment from most popular payments methods on different 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. 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 Low amount received. 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. Selected payment option 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 transactions 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. This Transaction was Declined by 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. This Transaction was Declined by 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.
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. Couldnt 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 get a link returned o the Hosted Cashier UI.

The payment session for this link expires after 30 min, only 1 payment is allowed for each session.

Authorizations:
Authorization
Request Body schema: application/json

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

For details about request payload data, please refer to Useful Data section.

country
required
string

Alpha-2 ISO Country code

currency
required
string

ISO Currency code

amount
required
integer

Decimal value allowing max two digits after the decimal point. If the amount is a crypto currency, 8 digits are allowed after the decimal point.

redirectUrl
required
string

Merchant redirect page after payment.

notificationUrl
string

Merchants notification webhook url. This value will override the notification URL setup in the Merchant Portal.

language
string

Alpha-2 ISO Language code

required
object

Json object with the following details.

merchantReference
string

Merchant reference, must be unique and generated in merchant system.

paymentReference
string

Reference to be used for the Payment.

userId
string

User identifier on the merchant system.

extra1
string

*Use this parameter for indicate the user crypto wallet.

extra2
string

Extra parameter to match payment.

extra3
string

Extra parameter to match payment.

storedToken
string

Stored payment credential.

tax
string

Tax percentage.

object

Shipping address object.

Array of objects

Array with products 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

Payout

Get Hosted Cashier link

Initiates a payout session and get a link returned o the Hosted Cashier UI.

The payout session for this link expires after 30 min, only 1 payout is allowed for each session.

Authorizations:
Authorization
Request Body schema: application/json

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

Alpha-2 ISO Country code.

currency
required
string

Alpha-3 ISO Currency code.

amount
required
integer

Decimal value allowing max two digits after the decimal point. If the amount is a crypto currency, 8 digits are allowed after the decimal point.

redirectUrl
required
string

Merchant page to be redirected after the payout.

notificationUrl
string

Merchants notification webhook url. This value will override the notification URL setup in the Merchant Portal.

required
object

Customer object with end user details, refer to Useful Data section for more information.

userId
string

User id generated by the merchant system.

language
string

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

extra1
string

Optional payload for help merchant to track this payout.

extra2
string

Optional payload for help merchant to track this payout.

extra3
string

Optional payload for help merchant to 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

Payin (v3)

Get Payment Options (Optional)

Get available payment options enabled for your merchant. The request can be filtered by country and currency. Response can be stored, it's not required to make this request for every transaction.

Authorizations:
Authorization
query Parameters
country
any
Examples:
  • country=DE -

Country code ISO alpha 2. Payment options not supported by the specified country will not be returned.

currency
any
Examples:
  • currency=USD -

Currency code ISO alpha 3. Payment options not supported by the specified currency will not be returned.

excludeCountries
any
Examples:
  • excludeCountries=false -

Boolean value. Whether to exclude the available countries from the response or not.

Responses

Response samples

Content type
application/json
Example
[
  • {
    }
]

Submit Payment

Endpoint for requesting a payment. In case when not all required data are included in this request the response will include a redirect URL. The URL will redirect the user to our Hosted Cashier to fulfill the missing information in order to carry out the payment.

Note: 3D secure authentication for card payment is used through a redirect URL. This redirect might contain an iframe and it may cause issues if redirected in another iframe

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

Your merchant api key.

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

Optional idempotency key, recommended to be a uuid. If the transaction is repeated with the same key, we will return the same response without re-trying the transaction.

Signature
string
Example: QGrW5AgToyf6wytINIdNVHiNwIHP9PvHIirGwgr88Jc=

Optional signature sha256 hash, to improve security. The content of the hash need to match this format paymentOptionId:merchantReference:currency:amount and be hashed with the signature key we provide for your merchant. Example payloads 4864ab16-2fa4-464a-b692-a74cab45aaf8::EUR:50.32, 4864ab16-2fa4-464a-b692-a74cab45aaf8:reference04322:USD:1000

Note: can be switched on on our side to be mandatory for your transactions.

Request Body schema: application/json
paymentOptionId
required
string

Selected payment option id. Ex. 4864ab16-2fa4-464a-b692-a74cab45aaf8 for cards. List of available payment options can be retrieved by using the Get Payment Options endpoint.

country
string = 2 characters

Country code ISO alpha 2. Should be set if possible, otherwise the customer will be redirected to the cashier to choose from a dropdown.

currency
required
string = 3 characters

Currency code ISO alpha 3.

amount
required
number

Decimal value allowing max two digits after the decimal point.

redirectUrl
string <= 500 characters

Merchant page to be redirected after the payment.

notificationUrl
string

Merchants notification webhook url. This value will override the notification URL setup in the Merchant Portal.

language
string = 3 characters

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

paymentData
object

Payment data object specific per payment option, ex. for card payments this will contain the card data. Please refer to the examples.

object

Customer object with end user details, some user data will be needed almost in all cases, it's recommended to provide as much data as possible, otherwise the customer will be redirected to the cashier to fill in the missing details.

merchantReference
string [ 1 .. 255 ] characters

Merchant reference, must be unique. If not provided, we will generate one ourselves.

paymentReference
string [ 1 .. 255 ] characters

Reference to be used for the Payment. If not provided, we will generate one ourselves.

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, it allow merchants to indicate productd details, like quantity, dimesions, description etc. Refer to 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 other action is needed

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

Confirm payment (only for P2P)

Additional Details request for APMs Payin will remain as “PENDING” until it is confirmed by using “action” parameter with the additional details requested: This call will send the additional details to the processor. This step is needed to ensure the transaction will be completed or it can be rejected by the processor.

Authorizations:
Authorization
Request Body schema: application/json

The Content-Type header should be set to application/json along with the merchant API key

sessionId
required
string

Internal session ID

essentialKey
required
string

Values: essentialKey eg +201001234565

Responses

Request samples

Content type
application/json
{
  • "sessionId": "dfa27e08-e6e4-4d87-8ca3-216445f11864",
  • "essentialKey": 201001234465
}

Response samples

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

Payout (v2)

1. Initiate a Payout

Retreive all the payout options allowed for country, currency and amount limits.

This endpoint returns all payout options based on a country. It’s a POST request with a json body specifing country, currency and amount for the payout.

Authorizations:
Authorization
Request Body schema: application/json

The Content-Type header should be set to application/json along with the merchant API key

country
required
string

Country code ISO alpha 2.

currency
required
string

Currency code ISO alpha 3.

amount
required
integer

Decimal value allowing max two digits after the decimal point. If the amount is a crypto currency, 8 digits are allowed after the decimal point.

redirectUrl
required
string

Merchant page to be redirected after the payout.

notificationUrl
string

Merchants notification webhook url. This value will override the notification URL setup in the Merchant Portal.

required
object

Customer object with end user details, refer to Useful Data section for more information.

merchantReference
string

Unique merchant specific reference for this transaction. If not set it will be generated. This reference will be returned in the notification.

merchantDomain
string

Merchant domain. Required for payment facilitators.

Responses

Request samples

Content type
application/json
{
  • "country": "AR",
  • "currency": "ARS",
  • "amount": 200,
  • "redirectUrl": "https://merchant.io/where-to-go",
  • "customer": {
    },
  • "merchantReference": "Unique merchant ref"
}

Response samples

Content type
application/json
[
  • {
    }
]

2. Get Payout Suboptions

Authorizations:
Authorization
Request Body schema: application/json

Use the sessionId and paymnentOptionId from the response of /payment-option

sessionId
required
string

UUID of the session generated previously.

paymentOptionId
required
string

UUID for chosen payment option.

Responses

Request samples

Content type
application/json
{
  • "sessionId": "string",
  • "paymentOptionId": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

3. Create Payout

Endpoint for initiate a payout request.

After the payout is accepted within the merchant system, it must be approved or declined from the merchant-portal or using the endpoint /settle-payout.

Authorizations:
Authorization
Request Body schema: application/json

The Content-Type header should be set to application/json along with the merchant API key

sessionId
string
paymentOptionId
string
optionId
string

Option id returned in the the payout-suboptions endpoint.

extraData
object

Necessary form input data needed to be set for this option

Responses

Request samples

Content type
application/json
{
  • "sessionId": "a6c13aa9-333d-4e07-b173-e37a71bcc7f3",
  • "paymentOptionId": "dfb7a9c4-1e87-4803-9929-091d946999d3",
  • "optionId": "d_316",
  • "extraData": {
    }
}

Response samples

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

4. Confirm Payout

Accept or reject a payout on using the direct API.

Payout will remain as “PENDING” until it is confirmed by using “action” parameter:

  • APPROVE a payout will submit all details to the payment processor, at this point the payout is processed but it could be rejected by processor.

  • DECLINE will reject the payout directly, and mark it as DECLINED in the system.

By default this is a mandatory step in the payout flow for security reasons. Contact your account manager if this step can be removed.

Authorizations:
Authorization
Request Body schema: application/json

The Content-Type header should be set to application/json along with the merchant API key

action
required
string

Values: APPROVE or DECLINE.

transactionId
required
string

Internal ID

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "statusCode": "000",
  • "status": "PROCESSING",
  • "transactionId": "1a48baf9-affe-4fde-9ccb-eafa32b478e2",
  • "merchantReference": "mr-65gkcsf2w23423",
  • "result": "Payout request was submitted successfully."
}

Refunds

Refund by Reference

Refund a previous authorized transaction

This endpoint will refund a previous authorized transaction, after this process the money will return to origin account. This process cannot be undone.

Authorizations:
Authorization
Request Body schema: application/json

The Content-Type header should be set to application/json along with the merchant API key

merchantReference
string

Reference of the transaction submitted by the merchant

Responses

Request samples

Content type
application/json
{
  • "merchantReference": "ac6c9d64-6ddb-449f-8789-4de064a4fa83"
}

Response samples

Content type
application/json
{
  • "statusCode": "000",
  • "errorReason": "Success",
  • "paymentAmount": 1000,
  • "status": "REFUNDED",
  • "currency": "BRL",
  • "country": "BR",
  • "paymentOptionName": "DepositExpress",
  • "userId": "merchantUser123",
  • "type": "All",
  • "_id": "feb6a715-9f7c-49d4-b6f7-10c59d18a194",
  • "createdAt": "02/09/2021 23:02:33",
  • "updatedAt": "02/09/2022 00:00:00"
}

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": {
    },
  • "createdAt": "2022-08-04T08:23:50.738Z",
  • "updatedAt": "2022-08-05T08:23:50.738Z"
}