payout / developers
API reference

Payout Payment API

Accept payments through a hosted payment form, refund them, and send money from your Payout balance to bank accounts.

  • Checkouts – create a payment, send the customer to the payment form and follow the payment status
  • Pre-authorization – authorize a card amount and capture or cancel it later
  • Refunds – return a paid checkout to the customer, in full or in part
  • M2M withdrawals – pay out from your balance to an IBAN over mTLS, signed with your QSEAL key
  • Payment methods and balance of your account
  • Certificates – import the QWAC and QSEAL certificates that M2M withdrawals need

To get access to the API, contact us at [email protected].

Environments

EnvironmentBase URL
Sandbox (for test purposes only)https://sandbox.payout.one
Productionhttps://app.payout.one

Authentication

Bearer token

Send a Bearer token in the Authorization header of every request except Get API token:

HTTP
Authorization: Bearer SFMyNTY.EXAMPLE-TOKEN.dGhpcy1pcy1hLWZha2Utc2lnbmF0dXJlLWV4YW1wbGU

Get the token from Get API token with the client_id and client_secret of an API key generated in the Admin section of your account. The token is valid for valid_for seconds (6000); then request a new one.

mTLS and QSEAL (M2M withdrawals)

M2M withdrawals run on separate mTLS hosts:

  • Sandbox – https://api-mtls-sandbox.payout.one
  • Production – https://api-mtls.payout.one

Besides the bearer token, every withdrawal request needs an approved QWAC presented in the TLS handshake. Requests that create or cancel a withdrawal are also signed with your QSEAL key in the Digest and X-JWS-Signature headers. See M2M Withdrawals and Certificates.

Errors

Errors are returned as JSON with an errors key. Its value is a message, or an object (or a list of objects) with messages per field. Send Accept: application/json with every request.

JSON
{
  "errors": "Unauthorized access. Check your token."
}

Each endpoint lists its own errors. These authentication errors can occur on any endpoint:

Status Message When
401 Bad credentials. Check your credentials or contact support. Wrong or missing client_id or client_secret at Get API token
401 Unauthorized access. Check your token. The token is missing or invalid
401 Unauthorized access. Token is expired. The token has expired
429 Too many failed authentication attempts for this client. Try again in a few minutes. 5 failed token requests for the same client_id within 5 minutes. Retry after the number of seconds in the Retry-After header
POST

Get API token

/api/v1/authorize

Exchanges the client_id and client_secret of your API key for a Bearer token. Send the token in the Authorization header of all other requests. The token is valid for valid_for seconds; then request a new one.

After 5 failed attempts for the same client_id within 5 minutes, the endpoint responds with 429. Retry after the number of seconds in the Retry-After header.

Request
curl -X POST 'https://sandbox.payout.one/api/v1/authorize' \
  -H "Content-Type: application/json" \
  -d '{
       "client_id": "8b0f3c52-6d1e-4a7b-9c2d-5e4f3a2b1c0d",
       "client_secret": "example-client-secret-not-real"
     }'
Response 200
{
  "token": "SFMyNTY.EXAMPLE-TOKEN.dGhpcy1pcy1hLWZha2Utc2lnbmF0dXJlLWV4YW1wbGU",
  "valid_for": 6000
}

Request body

client_id requiredstring

API key (client ID)

Example 8b0f3c52-6d1e-4a7b-9c2d-5e4f3a2b1c0d
client_secret requiredstring

API key secret

Example example-client-secret-not-real

Response 200

tokenstring

Bearer token for the Authorization header

Example SFMyNTY.EXAMPLE-TOKEN.dGhpcy1pcy1hLWZha2Utc2lnbmF0dXJlLWV4YW1wbGU
valid_forinteger

Token validity in seconds

Example 6000

Other responses

401

Wrong client_id or client_secret, or one of them is missing.

Example
{
  "errors": "Bad credentials. Check your credentials or contact support."
}
429

5 failed attempts for this client_id within 5 minutes. Retry after Retry-After seconds.

Example
{
  "errors": "Too many failed authentication attempts for this client. Try again in a few minutes."
}
POST

Create checkout

/api/v1/checkouts

Creates a checkout for a payment. Redirect your customer to the returned checkout_url to pay; afterwards they are sent to your redirect_url.

The response status shows the state of the checkout. To follow it later, call Retrieve checkout.

Idempotent requests

Send an Idempotency-Key header with a unique value, for example a v4 UUID. If a checkout with the same key already exists for your account, it is returned with status 200 instead of creating a new one. If that checkout has a different amount, the response is 409.

How to create the signature

  1. Join these values with |, in this order:
    1. amount, exactly as sent in the request
    2. currency
    3. external_id
    4. nonce
    5. client_secret of your API key
  2. Hash the string (amount|currency|external_id|nonce|client_secret) with SHA-256.
  3. Encode the hash as lowercase hex (Base16) and send it as signature.
Request
curl -X POST 'https://sandbox.payout.one/api/v1/checkouts' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
       "amount": 1050,
       "currency": "EUR",
       "customer": {
         "first_name": "John",
         "last_name": "Doe",
         "email": "[email protected]"
       },
       "external_id": "f0ac316a-9ea6-7998-01a7-720437afb34c",
       "nonce": "ZUc0Mk9sVXZDOXNsdklzMQ",
       "metadata": {
         "source": "eshop"
       },
       "redirect_url": "https://eshop.example.com/payment/redirect",
       "signature": "1bd312c9ee898c2a7d2c149c2f5557bad1b02bd7ccc00aa0248ca6b660940e04"
     }'
Response 201
{
  "object": "checkout",
  "id": 141447,
  "external_id": "f0ac316a-9ea6-7998-01a7-720437afb34c",
  "amount": 1050,
  "currency": "EUR",
  "redirect_url": "https://eshop.example.com/payment/redirect",
  "idempotency_key": null,
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "name": "John Doe",
    "email": "[email protected]",
    "phone": null,
    "note": null
  },
  "checkout_url": "https://sandbox.payout.one/checkouts/U0ZNeU5UWS5FWEFNUExFLUNIRUNLT1VULVRPS0VOLm5vdC1hLXJlYWwtc2lnbmF0dXJl/?account_id=RVhBTVBMRS1BQ0NPVU5ULVRPS0VOLTAwMDAwMDAwMDA",
  "metadata": {
    "source": "eshop"
  },
  "status": "processing",
  "nonce": "aEs3VG1QcVh6TjJ3Ylk4ZA",
  "signature": "cfbe2f29934d0cb90a37b2b54bdb73d32de99790a8414dc9e16624173776bf97",
  "payment": null,
  "all_payments": [],
  "billing_address": null,
  "shipping_address": null,
  "products": null,
  "payment_token": "U0ZNeU5UWS5FWEFNUExFLUNIRUNLT1VULVRPS0VOLm5vdC1hLXJlYWwtc2lnbmF0dXJl",
  "is_status_final": false
}

Parameters

Idempotency-Keyheader · string

Unique key of the request, for example a v4 UUID. A retry with the same key returns the object the first request created.

Max length 255 · Example 7c9e6679-7425-40de-944b-e07fc1f90ae7

Request body

amount requiredinteger

Amount in cents, for example 1050 for 10.50. A numeric string is also accepted.

Example 1050
currency requiredstring

Currency code by ISO 4217. Currencies not supported by Payout are rejected.

Max length 3 · Example EUR
customer requiredobject

Customer details. Send name, or first_name and last_name.

Show 6 child attributesHide child attributes
first_namestring

Customer first name

Max length 255 · Example John
last_namestring

Customer surname

Max length 255 · Example Doe
namestring

Customer full name. Can be sent instead of first_name and last_name; responses always contain it.

Example John Doe
email requiredstring

Customer email

Max length 255 · Example [email protected]
phonestring | null

Customer phone number. Characters other than digits and + are removed.

Example +421900000000
notestring | null

Note about the customer

external_id requiredstring

Your order ID or another reference for the payment

Max length 255 · Example f0ac316a-9ea6-7998-01a7-720437afb34c
idempotency_keystring

Stored with the checkout and returned in responses. Repeated requests are detected only by the Idempotency-Key header; when the header is sent, its value replaces this field.

Max length 255 · Example 7c9e6679-7425-40de-944b-e07fc1f90ae7
metadataobject

Your own data, returned with the checkout. For example the source of the payment if you have several systems.

Example {"source": "eshop"}
nonce requiredstring

Random string that is part of the signature

Example ZUc0Mk9sVXZDOXNsdklzMQ
redirect_url requiredstring

URL where the customer is sent after the payment form. Must be an absolute URL with a scheme and a host.

Example https://eshop.example.com/payment/redirect
signature requiredstring

Request signature, see How to create the signature

Example 1bd312c9ee898c2a7d2c149c2f5557bad1b02bd7ccc00aa0248ca6b660940e04
modestring

Checkout mode. Modes other than standard must be enabled for your account.

  • standardRegular payment
  • pre_authorizationOnly authorizes the amount on the card; capture or cancel it later
  • store_cardStores the card and sends its token in the payu_token.created webhook
  • card_on_filePays with a stored card; requires card_token
  • recurrentRecurrent payment with a stored card; requires recurrent_token
Default standard
recurringboolean

Only with mode: store_card. Send true when you will charge the stored card regularly (recurring payments); this requires recurrent payments to be enabled for your account.

Default false
recurrent_tokenstring

Token from the payu_token.created webhook. Required when mode is recurrent.

card_tokenstring

Token of a stored card from the payu_token.created webhook. Required when mode is card_on_file.

payment_methodstring

Payment method to open for the customer, for example card, apple_pay, pisp or bank_transfer. If the method is not available for your account, the customer sees all available methods.

List payment methods returns the methods enabled for your account. Checkout payment methods lists all identifiers, including the ones that open a single bank.

Example card
ibanstring

Customer's IBAN. Must be a valid IBAN.

Example SK3112000000198742637541
billing_addressobject

Billing address

Show 6 child attributesHide child attributes
name requiredstring
Example John Doe
address_line_1 requiredstring
Example Main Street 1
address_line_2string
Example Flat 2
postal_code requiredstring
Example 81101
city requiredstring
Example Bratislava
country_code requiredstring

Country code by ISO 3166-1 alpha-2

Max length 2 · Example SK
shipping_addressobject

Shipping address

Show 6 child attributesHide child attributes
name requiredstring
Example John Doe
address_line_1 requiredstring
Example Main Street 1
address_line_2string
Example Flat 2
postal_code requiredstring
Example 81101
city requiredstring
Example Bratislava
country_code requiredstring

Country code by ISO 3166-1 alpha-2

Max length 2 · Example SK
productsobject[]

Ordered products

Show 5 child attributesHide child attributes
name requiredstring
Example Product 1
unit_price requiredinteger

Unit price in cents

Example 350
quantity requiredinteger
Example 3
datestring<date>

Date of the product or service

Example 2026-10-20
offer_idstring

Offer ID used for transaction splitting

Example PREMIUM
should_splitboolean

Split the payment into one transaction per product offer_id (transaction splitting must be enabled for your account). The sum of unit_price * quantity of all products must equal amount.

Default false

Response 201

Returns a Checkout object.

Show 20 attributesHide attributes
objectstring

Object type

Example checkout
idinteger

Checkout ID

Example 141447
external_idstring

Your order ID or another reference for the payment

Example f0ac316a-9ea6-7998-01a7-720437afb34c
amountinteger

Amount in cents

Example 1050
currencystring

Currency code by ISO 4217

Example EUR
redirect_urlstring

URL where the customer is sent after the payment form

Example https://eshop.example.com/payment/redirect
idempotency_keystring | null

Idempotency-Key header (or idempotency_key field) of the request that created the checkout

Example 7c9e6679-7425-40de-944b-e07fc1f90ae7
customerobject

Customer details

Show 6 child attributesHide child attributes
first_namestring

Customer first name

Max length 255 · Example John
last_namestring

Customer surname

Max length 255 · Example Doe
namestring

Customer full name. Can be sent instead of first_name and last_name; responses always contain it.

Example John Doe
emailstring

Customer email

Max length 255 · Example [email protected]
phonestring | null

Customer phone number. Characters other than digits and + are removed.

Example +421900000000
notestring | null

Note about the customer

checkout_urlstring

URL of the payment form. Redirect your customer to it.

Example https://sandbox.payout.one/checkouts/U0ZNeU5UWS5FWEFNUExFLUNIRUNLT1VULVRPS0VOLm5vdC1hLXJlYWwtc2lnbmF0dXJl/?account_id=R…
metadataobject | null

Your own data sent with the checkout

Example {"source": "eshop"}
statusstring

Checkout status

  • processingCreated, waiting for the customer to pay
  • requires_authorizationCard payment soft-declined by the issuer; the next attempt requires 3-D Secure verification
  • requires_3dsWaiting for the customer to complete 3-D Secure verification of the card
  • pisp_processingBank payment (PISP) accepted by the bank, waiting for it to complete
  • awaiting_confirmationCard payment completed at the gateway, waiting for the gateway's notification
  • succeededPaid; with mode: pre_authorization, the amount is authorized and can be captured
  • expiredNot paid within the checkout expiration time of your account (10 days by default)
  • failedThe last payment attempt failed and the customer can try again. Also set when a pre-authorization is cancelled.
  • requires_payment_methodReserved – not currently set
  • requires_actionReserved – not currently set
  • requires_captureReserved – not currently set
  • cancelledReserved – not currently set; cancelling a pre-authorization sets failed. Withdrawals and refunds spell their status canceled.
noncestring

Random string Payout generates for the response signature

Example aEs3VG1QcVh6TjJ3Ylk4ZA
signaturestring

Response signature, see How to verify the signature

Example cfbe2f29934d0cb90a37b2b54bdb73d32de99790a8414dc9e16624173776bf97
paymentobject | null

Most recent payment or bank transfer (a successful one is preferred), null if there is none

Show 11 child attributesHide child attributes
objectstring

Object type

  • paymentPayment with a payment method such as a card
  • bank_transferManual bank transfer, matched to the checkout from Payout's bank statement
Example payment
statusstring

Status of the payment or bank transfer

  • pendingCreated, not confirmed by the acquirer yet (payment only)
  • in_transitMatched to the checkout, not reconciled yet (bank_transfer only)
  • successfulConfirmed by the acquirer, or the bank transfer is reconciled
  • failedFailed at the acquirer or bank
  • expiredBank transfer expired (bank_transfer only)
  • refundedFully refunded
  • partialy_refundedPartially refunded
payment_methodstring

Payment method identifier. card for all card payments and bank_transfer for bank transfers; other methods use their identifier from List payment methods, for example pisp.

Example card
failure_reasonstring

Payment failure reason (currently always an empty string)

Example ""
created_atinteger

Timestamp (Unix time in seconds)

Example 1759744800
fundsstring

How the net amount counts in your balance

  • pendingCounted in your pending balance
  • availableCounted in your available balance
  • onholdOn hold, not counted in your balance
  • canceledNot counted in your balance, for example because the payment failed
feeinteger

Fee in cents

Example 36
netinteger

Amount after fees, in cents

Example 1014
ibanstring | null

Payer IBAN from the bank statement. Only in bank_transfer objects.

Example CZ6508000000192000145399
account_detailsobject

Only for bank payments when payer name encryption is enabled for your account. name is encrypted with your API key, see Encrypted payer details in Retrieve checkout.

Show 1 child attributeHide child attributes
namestring

Encrypted payer name

Example <encrypted>
customerobject

Only for bank payments when payer IBAN encryption is enabled for your account. iban is encrypted with your API key, see Encrypted payer details in Retrieve checkout.

Show 1 child attributeHide child attributes
ibanstring

Encrypted payer IBAN

Example <encrypted>
all_paymentsobject[]

All payments and bank transfers of the checkout. Currently it stays empty unless the checkout has a bank transfer, so read payment for card and other payments.

Show 11 child attributesHide child attributes
objectstring

Object type

  • paymentPayment with a payment method such as a card
  • bank_transferManual bank transfer, matched to the checkout from Payout's bank statement
Example payment
statusstring

Status of the payment or bank transfer

  • pendingCreated, not confirmed by the acquirer yet (payment only)
  • in_transitMatched to the checkout, not reconciled yet (bank_transfer only)
  • successfulConfirmed by the acquirer, or the bank transfer is reconciled
  • failedFailed at the acquirer or bank
  • expiredBank transfer expired (bank_transfer only)
  • refundedFully refunded
  • partialy_refundedPartially refunded
payment_methodstring

Payment method identifier. card for all card payments and bank_transfer for bank transfers; other methods use their identifier from List payment methods, for example pisp.

Example card
failure_reasonstring

Payment failure reason (currently always an empty string)

Example ""
created_atinteger

Timestamp (Unix time in seconds)

Example 1759744800
fundsstring

How the net amount counts in your balance

  • pendingCounted in your pending balance
  • availableCounted in your available balance
  • onholdOn hold, not counted in your balance
  • canceledNot counted in your balance, for example because the payment failed
feeinteger

Fee in cents

Example 36
netinteger

Amount after fees, in cents

Example 1014
ibanstring | null

Payer IBAN from the bank statement. Only in bank_transfer objects.

Example CZ6508000000192000145399
account_detailsobject

Only for bank payments when payer name encryption is enabled for your account. name is encrypted with your API key, see Encrypted payer details in Retrieve checkout.

Show 1 child attributeHide child attributes
namestring

Encrypted payer name

Example <encrypted>
customerobject

Only for bank payments when payer IBAN encryption is enabled for your account. iban is encrypted with your API key, see Encrypted payer details in Retrieve checkout.

Show 1 child attributeHide child attributes
ibanstring

Encrypted payer IBAN

Example <encrypted>
billing_addressobject | null

Billing address, null if not sent

Show 6 child attributesHide child attributes
namestring
Example John Doe
address_line_1string
Example Main Street 1
address_line_2string
Example Flat 2
postal_codestring
Example 81101
citystring
Example Bratislava
country_codestring

Country code by ISO 3166-1 alpha-2

Max length 2 · Example SK
shipping_addressobject | null

Shipping address, null if not sent

Show 6 child attributesHide child attributes
namestring
Example John Doe
address_line_1string
Example Main Street 1
address_line_2string
Example Flat 2
postal_codestring
Example 81101
citystring
Example Bratislava
country_codestring

Country code by ISO 3166-1 alpha-2

Max length 2 · Example SK
productsobject[] | null

Ordered products, null if none were sent

Show 3 child attributesHide child attributes
namestring
Example Product 1
quantityinteger
Example 3
unit_priceinteger

Unit price in cents

Example 350
payment_tokenstring

Token used to complete the payment with Payout JS (for example Apple Pay)

Example U0ZNeU5UWS5FWEFNUExFLUNIRUNLT1VULVRPS0VOLm5vdC1hLXJlYWwtc2lnbmF0dXJl
is_status_finalboolean

Whether the checkout has reached a final state and will no longer change. Always true for succeeded checkouts.

Example false

Other responses

200

A checkout with the same Idempotency-Key already exists and is returned. It is returned without its payments (payment is null, all_payments is empty); call Retrieve checkout for its current state.

Example
{
  "object": "checkout",
  "id": 141447,
  "external_id": "f0ac316a-9ea6-7998-01a7-720437afb34c",
  "amount": 1050,
  "currency": "EUR",
  "redirect_url": "https://eshop.example.com/payment/redirect",
  "idempotency_key": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "+421900000000"
  },
  "checkout_url": "https://sandbox.payout.one/checkouts/U0ZNeU5UWS5FWEFNUExFLUNIRUNLT1VULVRPS0VOLm5vdC1hLXJlYWwtc2lnbmF0dXJl/?account_id=RVhBTVBMRS1BQ0NPVU5ULVRPS0VOLTAwMDAwMDAwMDA",
  "metadata": {
    "source": "eshop"
  },
  "status": "processing",
  "nonce": "aEs3VG1QcVh6TjJ3Ylk4ZA",
  "signature": "cfbe2f29934d0cb90a37b2b54bdb73d32de99790a8414dc9e16624173776bf97",
  "all_payments": [
    {
      "object": "payment",
      "status": "successful",
      "payment_method": "card",
      "failure_reason": "",
      "created_at": 1759744800,
      "funds": "available",
      "fee": 36,
      "net": 1014
    }
  ],
  "payment_token": "U0ZNeU5UWS5FWEFNUExFLUNIRUNLT1VULVRPS0VOLm5vdC1hLXJlYWwtc2lnbmF0dXJl",
  "is_status_final": false
}
400

Validation failed: errors lists one object per problem, or is a message for an unsupported mode

Example
{
  "errors": [
    {
      "signature": "Is invalid"
    },
    {
      "currency": "Currency not allowed."
    }
  ]
}
401

Missing, invalid or expired bearer token.

Example
{
  "errors": "Unauthorized access. Check your token."
}
403

Invalid recurrent_token or card_token

Example
{
  "errors": {
    "token": "invalid"
  }
}
409

A checkout with the same Idempotency-Key but a different amount already exists

Example
{
  "errors": "Checkout with this idempotency key already exists"
}
GET

List checkouts

/api/v1/checkouts

Lists the checkouts of your account, newest first. Page through them with limit and offset.

Request
curl -X GET 'https://sandbox.payout.one/api/v1/checkouts?limit=2' \
  -H "Authorization: Bearer $TOKEN"
Response 200
[
  {
    "object": "checkout",
    "id": 141448,
    "external_id": "5b2e9a41-0c7d-4f3e-8a6b-2d9c1e7f4a30",
    "amount": 2500,
    "currency": "EUR",
    "redirect_url": "https://eshop.example.com/payment/redirect",
    "idempotency_key": null,
    "customer": {
      "first_name": "Jane",
      "last_name": "Roe",
      "name": "Jane Roe",
      "email": "[email protected]",
      "phone": null,
      "note": null
    },
    "checkout_url": "https://sandbox.payout.one/checkouts/U0ZNeU5UWS5FWEFNUExFLUNIRUNLT1VULVRPS0VOLTIubm90LWEtcmVhbC1zaWduYXR1cmU/?account_id=RVhBTVBMRS1BQ0NPVU5ULVRPS0VOLTAwMDAwMDAwMDA",
    "metadata": {
      "source": "eshop"
    },
    "status": "processing",
    "nonce": "Wng0Q3ZCNm5NMXFMOHdFcg",
    "signature": "66bf7bd1e05e9279aaeed503adeed01f90c8e087a8fb2dc1f2b67419826c496d",
    "payment": null,
    "all_payments": [],
    "billing_address": null,
    "shipping_address": null,
    "products": null,
    "payment_token": "U0ZNeU5UWS5FWEFNUExFLUNIRUNLT1VULVRPS0VOLTIubm90LWEtcmVhbC1zaWduYXR1cmU",
    "is_status_final": false
  },
  {
    "object": "checkout",
    "id": 141447,
    "external_id": "f0ac316a-9ea6-7998-01a7-720437afb34c",
    "amount": 1050,
    "currency": "EUR",
    "redirect_url": "https://eshop.example.com/payment/redirect",
    "idempotency_key": null,
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "name": "John Doe",
      "email": "[email protected]",
      "phone": null,
      "note": null
    },
    "checkout_url": "https://sandbox.payout.one/checkouts/U0ZNeU5UWS5FWEFNUExFLUNIRUNLT1VULVRPS0VOLm5vdC1hLXJlYWwtc2lnbmF0dXJl/?account_id=RVhBTVBMRS1BQ0NPVU5ULVRPS0VOLTAwMDAwMDAwMDA",
    "metadata": {
      "source": "eshop"
    },
    "status": "succeeded",
    "nonce": "cFczZVl1N0tkRjlnSHMxQQ",
    "signature": "425a5778bb43ff12b6a755c4b7c74a64b025582be0dff694db477e623d124de0",
    "payment": {
      "object": "bank_transfer",
      "status": "successful",
      "payment_method": "bank_transfer",
      "iban": "CZ6508000000192000145399",
      "failure_reason": "",
      "created_at": 1759744800,
      "funds": "available",
      "fee": 10,
      "net": 1040
    },
    "all_payments": [
      {
        "object": "bank_transfer",
        "status": "successful",
        "payment_method": "bank_transfer",
        "iban": "CZ6508000000192000145399",
        "failure_reason": "",
        "created_at": 1759744800,
        "funds": "available",
        "fee": 10,
        "net": 1040
      }
    ],
    "billing_address": null,
    "shipping_address": null,
    "products": null,
    "payment_token": "U0ZNeU5UWS5FWEFNUExFLUNIRUNLT1VULVRPS0VOLm5vdC1hLXJlYWwtc2lnbmF0dXJl",
    "is_status_final": true
  }
]

Parameters

limitquery · integer

Maximum number of checkouts to return. There is no upper limit.

Default 10 · Example 2
offsetquery · integer

Number of checkouts to skip

Default 0

Response 200

Returns a list of Checkout objects.

Show 20 attributesHide attributes
objectstring

Object type

Example checkout
idinteger

Checkout ID

Example 141447
external_idstring

Your order ID or another reference for the payment

Example f0ac316a-9ea6-7998-01a7-720437afb34c
amountinteger

Amount in cents

Example 1050
currencystring

Currency code by ISO 4217

Example EUR
redirect_urlstring

URL where the customer is sent after the payment form

Example https://eshop.example.com/payment/redirect
idempotency_keystring | null

Idempotency-Key header (or idempotency_key field) of the request that created the checkout

Example 7c9e6679-7425-40de-944b-e07fc1f90ae7
customerobject

Customer details

Show 6 child attributesHide child attributes
first_namestring

Customer first name

Max length 255 · Example John
last_namestring

Customer surname

Max length 255 · Example Doe
namestring

Customer full name. Can be sent instead of first_name and last_name; responses always contain it.

Example John Doe
emailstring

Customer email

Max length 255 · Example [email protected]
phonestring | null

Customer phone number. Characters other than digits and + are removed.

Example +421900000000
notestring | null

Note about the customer

checkout_urlstring

URL of the payment form. Redirect your customer to it.

Example https://sandbox.payout.one/checkouts/U0ZNeU5UWS5FWEFNUExFLUNIRUNLT1VULVRPS0VOLm5vdC1hLXJlYWwtc2lnbmF0dXJl/?account_id=R…
metadataobject | null

Your own data sent with the checkout

Example {"source": "eshop"}
statusstring

Checkout status

  • processingCreated, waiting for the customer to pay
  • requires_authorizationCard payment soft-declined by the issuer; the next attempt requires 3-D Secure verification
  • requires_3dsWaiting for the customer to complete 3-D Secure verification of the card
  • pisp_processingBank payment (PISP) accepted by the bank, waiting for it to complete
  • awaiting_confirmationCard payment completed at the gateway, waiting for the gateway's notification
  • succeededPaid; with mode: pre_authorization, the amount is authorized and can be captured
  • expiredNot paid within the checkout expiration time of your account (10 days by default)
  • failedThe last payment attempt failed and the customer can try again. Also set when a pre-authorization is cancelled.
  • requires_payment_methodReserved – not currently set
  • requires_actionReserved – not currently set
  • requires_captureReserved – not currently set
  • cancelledReserved – not currently set; cancelling a pre-authorization sets failed. Withdrawals and refunds spell their status canceled.
noncestring

Random string Payout generates for the response signature

Example aEs3VG1QcVh6TjJ3Ylk4ZA
signaturestring

Response signature, see How to verify the signature

Example cfbe2f29934d0cb90a37b2b54bdb73d32de99790a8414dc9e16624173776bf97
paymentobject | null

Most recent payment or bank transfer (a successful one is preferred), null if there is none

Show 11 child attributesHide child attributes
objectstring

Object type

  • paymentPayment with a payment method such as a card
  • bank_transferManual bank transfer, matched to the checkout from Payout's bank statement
Example payment
statusstring

Status of the payment or bank transfer

  • pendingCreated, not confirmed by the acquirer yet (payment only)
  • in_transitMatched to the checkout, not reconciled yet (bank_transfer only)
  • successfulConfirmed by the acquirer, or the bank transfer is reconciled
  • failedFailed at the acquirer or bank
  • expiredBank transfer expired (bank_transfer only)
  • refundedFully refunded
  • partialy_refundedPartially refunded
payment_methodstring

Payment method identifier. card for all card payments and bank_transfer for bank transfers; other methods use their identifier from List payment methods, for example pisp.

Example card
failure_reasonstring

Payment failure reason (currently always an empty string)

Example ""
created_atinteger

Timestamp (Unix time in seconds)

Example 1759744800
fundsstring

How the net amount counts in your balance

  • pendingCounted in your pending balance
  • availableCounted in your available balance
  • onholdOn hold, not counted in your balance
  • canceledNot counted in your balance, for example because the payment failed
feeinteger

Fee in cents

Example 36
netinteger

Amount after fees, in cents

Example 1014
ibanstring | null

Payer IBAN from the bank statement. Only in bank_transfer objects.

Example CZ6508000000192000145399
account_detailsobject

Only for bank payments when payer name encryption is enabled for your account. name is encrypted with your API key, see Encrypted payer details in Retrieve checkout.

Show 1 child attributeHide child attributes
namestring

Encrypted payer name

Example <encrypted>
customerobject

Only for bank payments when payer IBAN encryption is enabled for your account. iban is encrypted with your API key, see Encrypted payer details in Retrieve checkout.

Show 1 child attributeHide child attributes
ibanstring

Encrypted payer IBAN

Example <encrypted>
all_paymentsobject[]

All payments and bank transfers of the checkout. Currently it stays empty unless the checkout has a bank transfer, so read payment for card and other payments.

Show 11 child attributesHide child attributes
objectstring

Object type

  • paymentPayment with a payment method such as a card
  • bank_transferManual bank transfer, matched to the checkout from Payout's bank statement
Example payment
statusstring

Status of the payment or bank transfer

  • pendingCreated, not confirmed by the acquirer yet (payment only)
  • in_transitMatched to the checkout, not reconciled yet (bank_transfer only)
  • successfulConfirmed by the acquirer, or the bank transfer is reconciled
  • failedFailed at the acquirer or bank
  • expiredBank transfer expired (bank_transfer only)
  • refundedFully refunded
  • partialy_refundedPartially refunded
payment_methodstring

Payment method identifier. card for all card payments and bank_transfer for bank transfers; other methods use their identifier from List payment methods, for example pisp.

Example card
failure_reasonstring

Payment failure reason (currently always an empty string)

Example ""
created_atinteger

Timestamp (Unix time in seconds)

Example 1759744800
fundsstring

How the net amount counts in your balance

  • pendingCounted in your pending balance
  • availableCounted in your available balance
  • onholdOn hold, not counted in your balance
  • canceledNot counted in your balance, for example because the payment failed
feeinteger

Fee in cents

Example 36
netinteger

Amount after fees, in cents

Example 1014
ibanstring | null

Payer IBAN from the bank statement. Only in bank_transfer objects.

Example CZ6508000000192000145399
account_detailsobject

Only for bank payments when payer name encryption is enabled for your account. name is encrypted with your API key, see Encrypted payer details in Retrieve checkout.

Show 1 child attributeHide child attributes
namestring

Encrypted payer name

Example <encrypted>
customerobject

Only for bank payments when payer IBAN encryption is enabled for your account. iban is encrypted with your API key, see Encrypted payer details in Retrieve checkout.

Show 1 child attributeHide child attributes
ibanstring

Encrypted payer IBAN

Example <encrypted>
billing_addressobject | null

Billing address, null if not sent

Show 6 child attributesHide child attributes
namestring
Example John Doe
address_line_1string
Example Main Street 1
address_line_2string
Example Flat 2
postal_codestring
Example 81101
citystring
Example Bratislava
country_codestring

Country code by ISO 3166-1 alpha-2

Max length 2 · Example SK
shipping_addressobject | null

Shipping address, null if not sent

Show 6 child attributesHide child attributes
namestring
Example John Doe
address_line_1string
Example Main Street 1
address_line_2string
Example Flat 2
postal_codestring
Example 81101
citystring
Example Bratislava
country_codestring

Country code by ISO 3166-1 alpha-2

Max length 2 · Example SK
productsobject[] | null

Ordered products, null if none were sent

Show 3 child attributesHide child attributes
namestring
Example Product 1
quantityinteger
Example 3
unit_priceinteger

Unit price in cents

Example 350
payment_tokenstring

Token used to complete the payment with Payout JS (for example Apple Pay)

Example U0ZNeU5UWS5FWEFNUExFLUNIRUNLT1VULVRPS0VOLm5vdC1hLXJlYWwtc2lnbmF0dXJl
is_status_finalboolean

Whether the checkout has reached a final state and will no longer change. Always true for succeeded checkouts.

Example false

Other responses

401

Missing, invalid or expired bearer token.

Example
{
  "errors": "Unauthorized access. Check your token."
}
GET

Retrieve checkout

/api/v1/checkouts/{checkout_id}

Returns a checkout of your account with its payments and bank transfers.

How to verify the signature

  1. Join these values from the response with |, in this order:
    1. amount
    2. currency
    3. external_id
    4. nonce
    5. client_secret of your API key
  2. Hash the string (amount|currency|external_id|nonce|client_secret) with SHA-256 and encode the hash as lowercase hex (Base16).
  3. Compare the result with signature from the response.

Encrypted payer details

Decrypt account_details.name and customer.iban of bank payments as described in Checkout verification webhook.

Request
curl -X GET 'https://sandbox.payout.one/api/v1/checkouts/141447' \
  -H "Authorization: Bearer $TOKEN"
Response 200
{
  "object": "checkout",
  "id": 141447,
  "external_id": "f0ac316a-9ea6-7998-01a7-720437afb34c",
  "amount": 1050,
  "currency": "EUR",
  "redirect_url": "https://eshop.example.com/payment/redirect",
  "idempotency_key": null,
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "name": "John Doe",
    "email": "[email protected]",
    "phone": null,
    "note": null
  },
  "checkout_url": "https://sandbox.payout.one/checkouts/U0ZNeU5UWS5FWEFNUExFLUNIRUNLT1VULVRPS0VOLm5vdC1hLXJlYWwtc2lnbmF0dXJl/?account_id=RVhBTVBMRS1BQ0NPVU5ULVRPS0VOLTAwMDAwMDAwMDA",
  "metadata": {
    "source": "eshop"
  },
  "status": "succeeded",
  "nonce": "UW00UnRMdzhYc1ZiMk5jSg",
  "signature": "b9128a278812b2299361b28cf9ecad93077c216534392176727e18d26823db3a",
  "payment": {
    "object": "bank_transfer",
    "status": "successful",
    "payment_method": "bank_transfer",
    "iban": "CZ6508000000192000145399",
    "failure_reason": "",
    "created_at": 1759744800,
    "funds": "available",
    "fee": 10,
    "net": 1040
  },
  "all_payments": [
    {
      "object": "bank_transfer",
      "status": "successful",
      "payment_method": "bank_transfer",
      "iban": "CZ6508000000192000145399",
      "failure_reason": "",
      "created_at": 1759744800,
      "funds": "available",
      "fee": 10,
      "net": 1040
    }
  ],
  "billing_address": null,
  "shipping_address": null,
  "products": null,
  "payment_token": "U0ZNeU5UWS5FWEFNUExFLUNIRUNLT1VULVRPS0VOLm5vdC1hLXJlYWwtc2lnbmF0dXJl",
  "is_status_final": true
}

Parameters

checkout_id requiredpath · integer

Checkout ID

Example 141447

Response 200

Returns a Checkout object.

Show 20 attributesHide attributes
objectstring

Object type

Example checkout
idinteger

Checkout ID

Example 141447
external_idstring

Your order ID or another reference for the payment

Example f0ac316a-9ea6-7998-01a7-720437afb34c
amountinteger

Amount in cents

Example 1050
currencystring

Currency code by ISO 4217

Example EUR
redirect_urlstring

URL where the customer is sent after the payment form

Example https://eshop.example.com/payment/redirect
idempotency_keystring | null

Idempotency-Key header (or idempotency_key field) of the request that created the checkout

Example 7c9e6679-7425-40de-944b-e07fc1f90ae7
customerobject

Customer details

Show 6 child attributesHide child attributes
first_namestring

Customer first name

Max length 255 · Example John
last_namestring

Customer surname

Max length 255 · Example Doe
namestring

Customer full name. Can be sent instead of first_name and last_name; responses always contain it.

Example John Doe
emailstring

Customer email

Max length 255 · Example [email protected]
phonestring | null

Customer phone number. Characters other than digits and + are removed.

Example +421900000000
notestring | null

Note about the customer

checkout_urlstring

URL of the payment form. Redirect your customer to it.

Example https://sandbox.payout.one/checkouts/U0ZNeU5UWS5FWEFNUExFLUNIRUNLT1VULVRPS0VOLm5vdC1hLXJlYWwtc2lnbmF0dXJl/?account_id=R…
metadataobject | null

Your own data sent with the checkout

Example {"source": "eshop"}
statusstring

Checkout status

  • processingCreated, waiting for the customer to pay
  • requires_authorizationCard payment soft-declined by the issuer; the next attempt requires 3-D Secure verification
  • requires_3dsWaiting for the customer to complete 3-D Secure verification of the card
  • pisp_processingBank payment (PISP) accepted by the bank, waiting for it to complete
  • awaiting_confirmationCard payment completed at the gateway, waiting for the gateway's notification
  • succeededPaid; with mode: pre_authorization, the amount is authorized and can be captured
  • expiredNot paid within the checkout expiration time of your account (10 days by default)
  • failedThe last payment attempt failed and the customer can try again. Also set when a pre-authorization is cancelled.
  • requires_payment_methodReserved – not currently set
  • requires_actionReserved – not currently set
  • requires_captureReserved – not currently set
  • cancelledReserved – not currently set; cancelling a pre-authorization sets failed. Withdrawals and refunds spell their status canceled.
noncestring

Random string Payout generates for the response signature

Example aEs3VG1QcVh6TjJ3Ylk4ZA
signaturestring

Response signature, see How to verify the signature

Example cfbe2f29934d0cb90a37b2b54bdb73d32de99790a8414dc9e16624173776bf97
paymentobject | null

Most recent payment or bank transfer (a successful one is preferred), null if there is none

Show 11 child attributesHide child attributes
objectstring

Object type

  • paymentPayment with a payment method such as a card
  • bank_transferManual bank transfer, matched to the checkout from Payout's bank statement
Example payment
statusstring

Status of the payment or bank transfer

  • pendingCreated, not confirmed by the acquirer yet (payment only)
  • in_transitMatched to the checkout, not reconciled yet (bank_transfer only)
  • successfulConfirmed by the acquirer, or the bank transfer is reconciled
  • failedFailed at the acquirer or bank
  • expiredBank transfer expired (bank_transfer only)
  • refundedFully refunded
  • partialy_refundedPartially refunded
payment_methodstring

Payment method identifier. card for all card payments and bank_transfer for bank transfers; other methods use their identifier from List payment methods, for example pisp.

Example card
failure_reasonstring

Payment failure reason (currently always an empty string)

Example ""
created_atinteger

Timestamp (Unix time in seconds)

Example 1759744800
fundsstring

How the net amount counts in your balance

  • pendingCounted in your pending balance
  • availableCounted in your available balance
  • onholdOn hold, not counted in your balance
  • canceledNot counted in your balance, for example because the payment failed
feeinteger

Fee in cents

Example 36
netinteger

Amount after fees, in cents

Example 1014
ibanstring | null

Payer IBAN from the bank statement. Only in bank_transfer objects.

Example CZ6508000000192000145399
account_detailsobject

Only for bank payments when payer name encryption is enabled for your account. name is encrypted with your API key, see Encrypted payer details in Retrieve checkout.

Show 1 child attributeHide child attributes
namestring

Encrypted payer name

Example <encrypted>
customerobject

Only for bank payments when payer IBAN encryption is enabled for your account. iban is encrypted with your API key, see Encrypted payer details in Retrieve checkout.

Show 1 child attributeHide child attributes
ibanstring

Encrypted payer IBAN

Example <encrypted>
all_paymentsobject[]

All payments and bank transfers of the checkout. Currently it stays empty unless the checkout has a bank transfer, so read payment for card and other payments.

Show 11 child attributesHide child attributes
objectstring

Object type

  • paymentPayment with a payment method such as a card
  • bank_transferManual bank transfer, matched to the checkout from Payout's bank statement
Example payment
statusstring

Status of the payment or bank transfer

  • pendingCreated, not confirmed by the acquirer yet (payment only)
  • in_transitMatched to the checkout, not reconciled yet (bank_transfer only)
  • successfulConfirmed by the acquirer, or the bank transfer is reconciled
  • failedFailed at the acquirer or bank
  • expiredBank transfer expired (bank_transfer only)
  • refundedFully refunded
  • partialy_refundedPartially refunded
payment_methodstring

Payment method identifier. card for all card payments and bank_transfer for bank transfers; other methods use their identifier from List payment methods, for example pisp.

Example card
failure_reasonstring

Payment failure reason (currently always an empty string)

Example ""
created_atinteger

Timestamp (Unix time in seconds)

Example 1759744800
fundsstring

How the net amount counts in your balance

  • pendingCounted in your pending balance
  • availableCounted in your available balance
  • onholdOn hold, not counted in your balance
  • canceledNot counted in your balance, for example because the payment failed
feeinteger

Fee in cents

Example 36
netinteger

Amount after fees, in cents

Example 1014
ibanstring | null

Payer IBAN from the bank statement. Only in bank_transfer objects.

Example CZ6508000000192000145399
account_detailsobject

Only for bank payments when payer name encryption is enabled for your account. name is encrypted with your API key, see Encrypted payer details in Retrieve checkout.

Show 1 child attributeHide child attributes
namestring

Encrypted payer name

Example <encrypted>
customerobject

Only for bank payments when payer IBAN encryption is enabled for your account. iban is encrypted with your API key, see Encrypted payer details in Retrieve checkout.

Show 1 child attributeHide child attributes
ibanstring

Encrypted payer IBAN

Example <encrypted>
billing_addressobject | null

Billing address, null if not sent

Show 6 child attributesHide child attributes
namestring
Example John Doe
address_line_1string
Example Main Street 1
address_line_2string
Example Flat 2
postal_codestring
Example 81101
citystring
Example Bratislava
country_codestring

Country code by ISO 3166-1 alpha-2

Max length 2 · Example SK
shipping_addressobject | null

Shipping address, null if not sent

Show 6 child attributesHide child attributes
namestring
Example John Doe
address_line_1string
Example Main Street 1
address_line_2string
Example Flat 2
postal_codestring
Example 81101
citystring
Example Bratislava
country_codestring

Country code by ISO 3166-1 alpha-2

Max length 2 · Example SK
productsobject[] | null

Ordered products, null if none were sent

Show 3 child attributesHide child attributes
namestring
Example Product 1
quantityinteger
Example 3
unit_priceinteger

Unit price in cents

Example 350
payment_tokenstring

Token used to complete the payment with Payout JS (for example Apple Pay)

Example U0ZNeU5UWS5FWEFNUExFLUNIRUNLT1VULVRPS0VOLm5vdC1hLXJlYWwtc2lnbmF0dXJl
is_status_finalboolean

Whether the checkout has reached a final state and will no longer change. Always true for succeeded checkouts.

Example false

Other responses

401

Missing, invalid or expired bearer token.

Example
{
  "errors": "Unauthorized access. Check your token."
}
403

The checkout belongs to another account

Example
{
  "errors": "Forbidden"
}
404

Checkout not found

Example
{
  "errors": "Not Found"
}
DELETE

Cancel pre-authorized checkout

/api/v1/checkouts/{checkout_id}

Cancels a checkout created with mode pre_authorization, for example when a product or service is not delivered. Only checkouts for which the checkout.captured webhook was not sent can be cancelled.

On success the checkout status changes to failed and the checkout.canceled webhook is sent. See also Capture and cancel.

Request
curl -X DELETE 'https://sandbox.payout.one/api/v1/checkouts/141447' \
  -H "Authorization: Bearer $TOKEN"
Response 200
"pre-auth canceled"

Parameters

checkout_id requiredpath · integer

Checkout ID

Example 141447

Responses

200

Pre-authorization cancelled

Example
pre-auth canceled
400

The checkout was not created with mode pre_authorization

Example
Unsupported operation
401

Missing, invalid or expired bearer token.

Example
{
  "errors": "Unauthorized access. Check your token."
}
403

The checkout belongs to another account

Example
{
  "errors": "Forbidden"
}
404

Checkout not found

Example
{
  "errors": "Not Found"
}
422

The acquirer refused the cancellation

Example
{
  "errors": "unable_to_cancel"
}
POST

Capture pre-authorized checkout

/api/v1/checkouts/{checkout_id}/capture

Captures the card amount authorized by a checkout created with mode pre_authorization. Pre-authorization must be enabled for your account.

Send an empty body to capture the whole authorized amount, or amount for a partial capture. After a successful capture the checkout.captured webhook is sent. See also Capture and cancel.

Request
curl -X POST 'https://sandbox.payout.one/api/v1/checkouts/141447/capture' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
       "amount": 150
     }'
Response 200
"captured"

Parameters

checkout_id requiredpath · integer

Checkout ID

Example 141447

Request body

amountinteger

Amount to capture in cents. It must not be larger than the checkout amount. A numeric string is also accepted. Omit it to capture the whole amount.

Example 150

Responses

200

Captured

Example
captured
400

amount is larger than the checkout amount

Example
{
  "status": "Partial capture amount is larger than checkout amount"
}
401

Missing, invalid or expired bearer token.

Example
{
  "errors": "Unauthorized access. Check your token."
}
403

The checkout belongs to another account

Example
{
  "errors": "Forbidden"
}
404

Checkout not found

Example
{
  "errors": "Not Found"
}
422

The acquirer refused the capture

Example
{
  "errors": "unable_to_capture"
}
GET

Retrieve payment instructions

/api/v1/checkouts/{checkout_id}/payment_instructions

Returns the bank details and QR code your customer needs to pay a checkout by manual bank transfer. No email is sent; use it to show the instructions in your own UI. See Payment instructions.

Bank transfer must be enabled for your account in the checkout currency. The QR code is cached, so repeated calls for the same checkout return the same image and are safe to retry.

Request
curl -X GET 'https://sandbox.payout.one/api/v1/checkouts/141447/payment_instructions' \
  -H "Authorization: Bearer $TOKEN"
Response 200
{
  "recipient_name": "Payout a.s.",
  "iban": "SK3112000000198742637541",
  "account_number": "000019-8742637541/1200",
  "variable_symbol": "1000123411",
  "amount": "10.5000",
  "currency": "EUR",
  "qr_code": "iVBORw0KGgoAAAANSUhEUgAAAX8AAAHBCAYAAACBh..."
}

Parameters

checkout_id requiredpath · integer

Checkout ID

Example 141447

Response 200

recipient_namestring

Name of the beneficiary the customer should send the money to

Example Payout a.s.
ibanstring

Beneficiary IBAN in international format

Example SK3112000000198742637541
account_numberstring | null

Beneficiary account in local format (prefix-account/bank_code). Filled for Czech (CZ) and Slovak (SK) IBANs, otherwise null.

Example 000019-8742637541/1200
variable_symbolstring

Variable symbol the customer must include in the transfer. It binds the incoming payment to the checkout.

Example 1000123411
amountstring

Total amount to transfer, decimal string (not in cents)

Example 10.5000
currencystring

Currency code by ISO 4217

Example EUR
qr_codestring

Base64-encoded PNG of the payment QR code

Example iVBORw0KGgoAAAANSUhEUgAAAX8AAAHBCAYAAACBh...

Other responses

401

Missing, invalid or expired bearer token.

Example
{
  "errors": "Unauthorized access. Check your token."
}
403

The checkout belongs to another account

Example
{
  "errors": "Forbidden"
}
404

Checkout not found

Example
{
  "errors": "Not Found"
}
409

Bank transfer is not enabled for your account in the checkout currency

Example
{
  "errors": "Bank transfer not enabled for this account."
}
410

The checkout has expired

Example
{
  "errors": "Checkout has expired."
}
422

No beneficiary bank account is available for the checkout currency

Example
{
  "errors": "No bank account available for this currency."
}
500

The QR code could not be generated; the request is safe to repeat

Example
{
  "errors": "Failed to generate QR code."
}
POST

Refund payment

/api/v1/refunds

Refunds a paid checkout to the original customer.

Send amount for a partial refund; without it, the whole amount that has not been refunded yet is refunded. Depending on the payment method, only a full refund may be possible. For checkouts created with should_split: true, offer_id is required and selects the split transaction to refund, see Transaction Splitting.

The refunded amount and the refund fees are deducted from your available balance.

How to create the signature

  1. Join these values with |, in this order:
    1. amount exactly as sent in the request. If you omit amount, use the checkout amount in cents, even when part of it was already refunded.
    2. currency of the checkout
    3. external_id of the checkout
    4. iban as sent in the request, or empty if you omit it
    5. nonce
    6. client_secret of your API key
  2. Hash the string (amount|currency|external_id|iban|nonce|client_secret) with SHA-256.
  3. Encode the hash as lowercase hex (Base16) and send it as signature.

How to verify the response signature

  1. Join these values from the response with |, in this order:
    1. amount
    2. currency
    3. external_id
    4. an empty value (the response has no IBAN)
    5. nonce
    6. client_secret of your API key
  2. Hash the string (amount|currency|external_id||nonce|client_secret) with SHA-256 and encode the hash as lowercase hex (Base16).
  3. Compare the result with signature from the response.
Request
curl -X POST 'https://sandbox.payout.one/api/v1/refunds' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
       "checkout_id": 141447,
       "amount": 500,
       "statement_descriptor": "Refund for order 1001",
       "nonce": "cnd0aXJ0cnVuZXg",
       "signature": "1197e50f076dec439cf1b47e6905aa95aacc7d593954a224496a7c350faeaa27"
     }'
Response 200
{
  "id": 52332,
  "object": "refund",
  "amount": 500,
  "currency": "EUR",
  "external_id": "f0ac316a-9ea6-7998-01a7-720437afb34c",
  "idempotency_key": null,
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "name": "John Doe",
    "email": "[email protected]",
    "phone": null,
    "note": null
  },
  "status": "pending",
  "metadata": {},
  "statement_descriptor": "Refund for order 1001",
  "created_at": 1759831200,
  "nonce": "TGs5SmhHM2ZEczVBcVo3eA",
  "signature": "addd0a0ef36320a8d8f041a092c7600f54678521b18fa738f6bc0cf664c61598"
}

Request body

checkout_id requiredinteger

ID of the paid checkout to refund

Example 141447
amountinteger

Amount to refund in cents, for example 500 for 5.00. A numeric string is also accepted. Without it, the whole amount that has not been refunded yet is refunded.

Example 500
ibanstring

Customer's IBAN. It is only used in the signature; the refund goes to the original customer.

Example SK3112000000198742637541
statement_descriptorstring

Text for the recipient's bank statement. Only letters without accents, digits, spaces and the characters /-?:().,'+ are allowed.

Max length 140 · Example Refund for order 1001
offer_idstring

Offer ID of the split transaction to refund. Required for checkouts created with should_split: true.

Example PREMIUM
nonce requiredstring

Random string that is part of the signature

Example cnd0aXJ0cnVuZXg
signature requiredstring

Request signature, see How to create the signature

Example 1197e50f076dec439cf1b47e6905aa95aacc7d593954a224496a7c350faeaa27

Response 200

idinteger

Refund ID

Example 52332
objectstring

Object type

Example refund
amountinteger

Amount in cents

Example 500
currencystring

Currency code by ISO 4217

Example EUR
external_idstring

external_id of the refunded checkout

Example f0ac316a-9ea6-7998-01a7-720437afb34c
idempotency_keynull

Always null; refunds have no idempotency key

customerobject

Customer details

Show 6 child attributesHide child attributes
first_namestring

Customer first name

Max length 255 · Example John
last_namestring

Customer surname

Max length 255 · Example Doe
namestring

Customer full name. Can be sent instead of first_name and last_name; responses always contain it.

Example John Doe
emailstring

Customer email

Max length 255 · Example [email protected]
phonestring | null

Customer phone number. Characters other than digits and + are removed.

Example +421900000000
notestring | null

Note about the customer

statusstring

Refund status

  • pendingCreated, not sent to the bank (or, for a card refund, to the acquirer) yet. Withdrawals held because they exceed your account's withdrawal limits are also pending. Only pending withdrawals can be cancelled.
  • in_transitSent to the bank, waiting for the bank to execute it
  • paidExecuted by the bank (confirmed by the bank or found on Payout's bank statement); for a card refund, confirmed by the acquirer
  • canceledCancelled before it was executed, by you or by Payout. The amount and fees are returned to your available balance. Spelled canceled; checkouts use cancelled.
  • failedRejected by the bank or could not be executed. The amount and fees are returned to your available balance.
metadataobject

Always an empty object

Example {}
statement_descriptorstring | null

Text for the recipient's bank statement

Example Refund for order 1001
created_atinteger

Timestamp (Unix time in seconds)

Example 1759831200
noncestring

Random string Payout generates for the response signature

Example TGs5SmhHM2ZEczVBcVo3eA
signaturestring

Response signature, see How to verify the response signature

Example addd0a0ef36320a8d8f041a092c7600f54678521b18fa738f6bc0cf664c61598

Other responses

400

The payment cannot be refunded, for example it is not paid yet, was already refunded, or your available balance is too low; errors names the reason

Example
{
  "errors": {
    "payment": "wasn't paid yet"
  }
}
401

Missing, invalid or expired bearer token.

Example
{
  "errors": "Unauthorized access. Check your token."
}
403

Invalid signature, see How to create the signature

Example
{
  "errors": {
    "signature": "Is invalid"
  }
}
404

Checkout not found

Example
{
  "errors": {
    "checkout": "wasn't found"
  }
}
422

The refund could not be created (for example, no split transaction for the given offer_id)

Example
{
  "errors": "split_transaction_not_found"
}
POST

Create withdrawal

/api/v2/withdrawals on api-mtls-sandbox.payout.one · api-mtls.payout.one

Sends money from your Payout balance to the given IBAN. A new withdrawal has status pending; its amount and fees are deducted from your available balance right away.

Call it on the mTLS host with an approved QWAC and sign it with your QSEAL key in the Digest and X-JWS-Signature headers. How to build the signature is described in M2M Withdrawals; how to get and import the certificates in Certificates.

Idempotent requests

Send an Idempotency-Key header with a unique value. If a withdrawal with the same key already exists for your account, it is returned with status 200 instead of creating a new one.

Request
BODY='{
  "amount": 1050,
  "currency": "EUR",
  "external_id": "PAYOUT-2026-0001",
  "iban": "SK3112000000198742637541",
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]"
  },
  "statement_descriptor": "Payout for order 1001"
}'
DIGEST="SHA-256=$(printf %s "$BODY" | openssl dgst -sha256 -binary | base64)"
# QSEAL key, see M2M Withdrawals: Signing payment instructions with QSEAL
JWS_SIGNATURE="<detached JWS over $DIGEST>"

curl -X POST 'https://api-mtls-sandbox.payout.one/api/v2/withdrawals' \
  --cert qwac.pem --key qwac.key \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Digest: $DIGEST" \
  -H "X-JWS-Signature: $JWS_SIGNATURE" \
  -d "$BODY"
Response 201
{
  "id": 52331,
  "object": "withdrawal",
  "amount": 1050,
  "api_key_id": 42,
  "currency": "EUR",
  "external_id": "PAYOUT-2026-0001",
  "iban": "SK3112000000198742637541",
  "idempotency_key": null,
  "status": "pending",
  "metadata": {},
  "statement_descriptor": "Payout for order 1001",
  "created_at": 1759744800,
  "nonce": "VGc1SGpLMm1OYjdWY1gzeg",
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "name": "John Doe",
    "email": "[email protected]",
    "phone": null,
    "note": null
  },
  "signature": "46d36aad1153a6195e6a1db51d0d49d2008acc5c264562b5da30c40e355ce71c"
}

Parameters

Idempotency-Keyheader · string

Unique key of the request, for example a v4 UUID. A retry with the same key returns the object the first request created.

Max length 255 · Example 7c9e6679-7425-40de-944b-e07fc1f90ae7
Digest requiredheader · string

SHA-256= followed by the Base64 SHA-256 of the exact request body (of an empty body when there is none)

Example SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
X-JWS-Signature requiredheader · string

Detached JWS (<protected header>..<signature>) over the Digest value, made with your QSEAL key. The protected header carries x5t#S256 (QSEAL thumbprint) and sigT (signing time, at most 5 minutes off).

Example eyJhbGciOiJQUzI1NiIsIng1dCNTMjU2IjoiLi4uIn0..c2lnbmF0dXJl

Request body

amount requiredinteger

Amount in cents, for example 1050 for 10.50. A numeric string is also accepted.

Example 1050
currency requiredstring

Currency code by ISO 4217. Currencies not supported by Payout are rejected.

Max length 3 · Example EUR
iban requiredstring

IBAN of the bank account the amount is sent to

Example SK3112000000198742637541
customer requiredobject

Recipient details. Send name, or first_name and last_name.

Show 6 child attributesHide child attributes
first_namestring

Customer first name

Max length 255 · Example John
last_namestring

Customer surname

Max length 255 · Example Doe
namestring

Customer full name. Can be sent instead of first_name and last_name; responses always contain it.

Example John Doe
email requiredstring

Customer email

Max length 255 · Example [email protected]
phonestring | null

Customer phone number. Characters other than digits and + are removed.

Example +421900000000
notestring | null

Note about the customer

external_idstring

Your reference for the withdrawal, returned with it

Max length 255 · Example PAYOUT-2026-0001
statement_descriptorstring

Text for the recipient's bank statement. Only letters without accents, digits, spaces and the characters /-?:().,'+ are allowed.

Max length 140 · Example Payout for order 1001

Response 201

Returns a Withdrawal object.

Show 15 attributesHide attributes
idinteger

Withdrawal ID

Example 52331
objectstring

Object type

Example withdrawal
amountinteger

Amount in cents

Example 1050
api_key_idinteger | null

ID of the API key that created the withdrawal, null if it was not created through the API

Example 42
currencystring

Currency code by ISO 4217

Example EUR
external_idstring | null

Your reference for the withdrawal

Example PAYOUT-2026-0001
ibanstring

IBAN of the recipient

Example SK3112000000198742637541
idempotency_keystring | null

Idempotency-Key header of the request that created the withdrawal

Example 7c9e6679-7425-40de-944b-e07fc1f90ae7
statusstring

Withdrawal status

  • pendingCreated, not sent to the bank (or, for a card refund, to the acquirer) yet. Withdrawals held because they exceed your account's withdrawal limits are also pending. Only pending withdrawals can be cancelled.
  • in_transitSent to the bank, waiting for the bank to execute it
  • paidExecuted by the bank (confirmed by the bank or found on Payout's bank statement); for a card refund, confirmed by the acquirer
  • canceledCancelled before it was executed, by you or by Payout. The amount and fees are returned to your available balance. Spelled canceled; checkouts use cancelled.
  • failedRejected by the bank or could not be executed. The amount and fees are returned to your available balance.
metadataobject

Additional data Payout stores with the withdrawal. Empty for withdrawals created through the API.

Example {}
statement_descriptorstring | null

Text for the recipient's bank statement

Example Payout for order 1001
created_atinteger

Timestamp (Unix time in seconds)

Example 1759744800
noncestring

Random string Payout generates for the response signature

Example VGc1SGpLMm1OYjdWY1gzeg
customerobject

Recipient details

Show 6 child attributesHide child attributes
first_namestring

Customer first name

Max length 255 · Example John
last_namestring

Customer surname

Max length 255 · Example Doe
namestring

Customer full name. Can be sent instead of first_name and last_name; responses always contain it.

Example John Doe
emailstring

Customer email

Max length 255 · Example [email protected]
phonestring | null

Customer phone number. Characters other than digits and + are removed.

Example +421900000000
notestring | null

Note about the customer

signaturestring

Response signature, see How to verify the signature

Example 46d36aad1153a6195e6a1db51d0d49d2008acc5c264562b5da30c40e355ce71c

Other responses

200

A withdrawal with the same Idempotency-Key already exists and is returned

Example
{
  "id": 52331,
  "object": "withdrawal",
  "amount": 1050,
  "api_key_id": 42,
  "currency": "EUR",
  "external_id": "PAYOUT-2026-0001",
  "iban": "SK3112000000198742637541",
  "idempotency_key": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "pending",
  "metadata": {},
  "statement_descriptor": "Payout for order 1001",
  "created_at": 1759744800,
  "nonce": "VGc1SGpLMm1OYjdWY1gzeg",
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "+421900000000"
  },
  "signature": "46d36aad1153a6195e6a1db51d0d49d2008acc5c264562b5da30c40e355ce71c"
}
400

Missing iban, not enough balance, or the currency is invalid or not allowed

Example
{
  "errors": "Not enough balance for withdrawal."
}
401

Missing, invalid or expired bearer token.

Example
{
  "errors": "Unauthorized access. Check your token."
}
403

The QWAC or the QSEAL signature was not accepted, for example the certificate is not approved or belongs to another account, Digest does not match the body, or sigT is more than 5 minutes off

Example
{
  "errors": "Forbidden"
}
404

Not the mTLS host (empty response)

422

Validation failed (errors per field, for example a blocked IBAN, or the amount plus fees would exceed your available balance), or the risk check refused the withdrawal

Example
{
  "errors": {
    "account_customer": {
      "iban": [
        "is blocked"
      ]
    }
  }
}
GET

List withdrawals

/api/v2/withdrawals on api-mtls-sandbox.payout.one · api-mtls.payout.one

Lists the withdrawals of your account, newest first by default. Read-only requests need the bearer token and the QWAC, no QSEAL signature.

Request
curl -X GET 'https://api-mtls-sandbox.payout.one/api/v2/withdrawals?limit=10' \
  --cert qwac.pem --key qwac.key \
  -H "Authorization: Bearer $TOKEN"
Response 200
[
  {
    "id": 52331,
    "object": "withdrawal",
    "amount": 1050,
    "api_key_id": 42,
    "currency": "EUR",
    "external_id": "PAYOUT-2026-0001",
    "iban": "SK3112000000198742637541",
    "idempotency_key": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "status": "pending",
    "metadata": {},
    "statement_descriptor": "Payout for order 1001",
    "created_at": 1759744800,
    "nonce": "VGc1SGpLMm1OYjdWY1gzeg",
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+421900000000"
    },
    "signature": "46d36aad1153a6195e6a1db51d0d49d2008acc5c264562b5da30c40e355ce71c"
  }
]

Parameters

limitquery · integer

Maximum number of withdrawals to return. Without it, all withdrawals are returned.

Example 10
offsetquery · integer

Number of withdrawals to skip

Default 0
orderquery · string

Sort order by withdrawal ID, case-insensitive. Any other value sorts DESC.

One of ASC, DESC · Default DESC

Response 200

Returns a list of Withdrawal objects.

Show 15 attributesHide attributes
idinteger

Withdrawal ID

Example 52331
objectstring

Object type

Example withdrawal
amountinteger

Amount in cents

Example 1050
api_key_idinteger | null

ID of the API key that created the withdrawal, null if it was not created through the API

Example 42
currencystring

Currency code by ISO 4217

Example EUR
external_idstring | null

Your reference for the withdrawal

Example PAYOUT-2026-0001
ibanstring

IBAN of the recipient

Example SK3112000000198742637541
idempotency_keystring | null

Idempotency-Key header of the request that created the withdrawal

Example 7c9e6679-7425-40de-944b-e07fc1f90ae7
statusstring

Withdrawal status

  • pendingCreated, not sent to the bank (or, for a card refund, to the acquirer) yet. Withdrawals held because they exceed your account's withdrawal limits are also pending. Only pending withdrawals can be cancelled.
  • in_transitSent to the bank, waiting for the bank to execute it
  • paidExecuted by the bank (confirmed by the bank or found on Payout's bank statement); for a card refund, confirmed by the acquirer
  • canceledCancelled before it was executed, by you or by Payout. The amount and fees are returned to your available balance. Spelled canceled; checkouts use cancelled.
  • failedRejected by the bank or could not be executed. The amount and fees are returned to your available balance.
metadataobject

Additional data Payout stores with the withdrawal. Empty for withdrawals created through the API.

Example {}
statement_descriptorstring | null

Text for the recipient's bank statement

Example Payout for order 1001
created_atinteger

Timestamp (Unix time in seconds)

Example 1759744800
noncestring

Random string Payout generates for the response signature

Example VGc1SGpLMm1OYjdWY1gzeg
customerobject

Recipient details

Show 6 child attributesHide child attributes
first_namestring

Customer first name

Max length 255 · Example John
last_namestring

Customer surname

Max length 255 · Example Doe
namestring

Customer full name. Can be sent instead of first_name and last_name; responses always contain it.

Example John Doe
emailstring

Customer email

Max length 255 · Example [email protected]
phonestring | null

Customer phone number. Characters other than digits and + are removed.

Example +421900000000
notestring | null

Note about the customer

signaturestring

Response signature, see How to verify the signature

Example 46d36aad1153a6195e6a1db51d0d49d2008acc5c264562b5da30c40e355ce71c

Other responses

401

Missing, invalid or expired bearer token.

Example
{
  "errors": "Unauthorized access. Check your token."
}
403

No approved QWAC presented in the TLS handshake, or the certificate belongs to another account

Example
{
  "errors": "Forbidden"
}
404

Not the mTLS host (empty response)

GET

Retrieve withdrawal

/api/v2/withdrawals/{withdrawal_id} on api-mtls-sandbox.payout.one · api-mtls.payout.one

Returns one withdrawal of your account. Read-only requests need the bearer token and the QWAC, no QSEAL signature.

How to verify the signature

  1. Join these values from the response with |, in this order:
    1. amount
    2. currency
    3. external_id (empty when null)
    4. iban
    5. nonce
    6. client_secret of your API key
  2. Hash the string (amount|currency|external_id|iban|nonce|client_secret) with SHA-256 and encode the hash as lowercase hex (Base16).
  3. Compare the result with signature from the response.
Request
curl -X GET 'https://api-mtls-sandbox.payout.one/api/v2/withdrawals/52331' \
  --cert qwac.pem --key qwac.key \
  -H "Authorization: Bearer $TOKEN"
Response 200
{
  "id": 52331,
  "object": "withdrawal",
  "amount": 1050,
  "api_key_id": 42,
  "currency": "EUR",
  "external_id": "PAYOUT-2026-0001",
  "iban": "SK3112000000198742637541",
  "idempotency_key": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "pending",
  "metadata": {},
  "statement_descriptor": "Payout for order 1001",
  "created_at": 1759744800,
  "nonce": "VGc1SGpLMm1OYjdWY1gzeg",
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "+421900000000"
  },
  "signature": "46d36aad1153a6195e6a1db51d0d49d2008acc5c264562b5da30c40e355ce71c"
}

Parameters

withdrawal_id requiredpath · integer

Withdrawal ID

Example 52331

Response 200

Returns a Withdrawal object.

Show 15 attributesHide attributes
idinteger

Withdrawal ID

Example 52331
objectstring

Object type

Example withdrawal
amountinteger

Amount in cents

Example 1050
api_key_idinteger | null

ID of the API key that created the withdrawal, null if it was not created through the API

Example 42
currencystring

Currency code by ISO 4217

Example EUR
external_idstring | null

Your reference for the withdrawal

Example PAYOUT-2026-0001
ibanstring

IBAN of the recipient

Example SK3112000000198742637541
idempotency_keystring | null

Idempotency-Key header of the request that created the withdrawal

Example 7c9e6679-7425-40de-944b-e07fc1f90ae7
statusstring

Withdrawal status

  • pendingCreated, not sent to the bank (or, for a card refund, to the acquirer) yet. Withdrawals held because they exceed your account's withdrawal limits are also pending. Only pending withdrawals can be cancelled.
  • in_transitSent to the bank, waiting for the bank to execute it
  • paidExecuted by the bank (confirmed by the bank or found on Payout's bank statement); for a card refund, confirmed by the acquirer
  • canceledCancelled before it was executed, by you or by Payout. The amount and fees are returned to your available balance. Spelled canceled; checkouts use cancelled.
  • failedRejected by the bank or could not be executed. The amount and fees are returned to your available balance.
metadataobject

Additional data Payout stores with the withdrawal. Empty for withdrawals created through the API.

Example {}
statement_descriptorstring | null

Text for the recipient's bank statement

Example Payout for order 1001
created_atinteger

Timestamp (Unix time in seconds)

Example 1759744800
noncestring

Random string Payout generates for the response signature

Example VGc1SGpLMm1OYjdWY1gzeg
customerobject

Recipient details

Show 6 child attributesHide child attributes
first_namestring

Customer first name

Max length 255 · Example John
last_namestring

Customer surname

Max length 255 · Example Doe
namestring

Customer full name. Can be sent instead of first_name and last_name; responses always contain it.

Example John Doe
emailstring

Customer email

Max length 255 · Example [email protected]
phonestring | null

Customer phone number. Characters other than digits and + are removed.

Example +421900000000
notestring | null

Note about the customer

signaturestring

Response signature, see How to verify the signature

Example 46d36aad1153a6195e6a1db51d0d49d2008acc5c264562b5da30c40e355ce71c

Other responses

401

Missing, invalid or expired bearer token.

Example
{
  "errors": "Unauthorized access. Check your token."
}
403

No approved QWAC presented in the TLS handshake, or the certificate belongs to another account; or the withdrawal belongs to another account

Example
{
  "errors": "Forbidden"
}
404

Withdrawal not found, or not the mTLS host

POST

Cancel withdrawal

/api/v2/withdrawals/{withdrawal_id}/cancel on api-mtls-sandbox.payout.one · api-mtls.payout.one

Cancels a withdrawal that is still pending and has not been passed to the bank yet. Its amount and fees are returned to your available balance. Sign the request with QSEAL like Create withdrawal; it has no body, so Digest is the SHA-256 of an empty body.

Both outcomes return 200: the cancelled withdrawal, or allowed: false with the current status when the withdrawal can no longer be cancelled. To check in advance, call Check if cancellable.

Request
BODY=''
DIGEST="SHA-256=$(printf %s "$BODY" | openssl dgst -sha256 -binary | base64)"
# QSEAL key, see M2M Withdrawals: Signing payment instructions with QSEAL
JWS_SIGNATURE="<detached JWS over $DIGEST>"

curl -X POST 'https://api-mtls-sandbox.payout.one/api/v2/withdrawals/52331/cancel' \
  --cert qwac.pem --key qwac.key \
  -H "Authorization: Bearer $TOKEN" \
  -H "Digest: $DIGEST" \
  -H "X-JWS-Signature: $JWS_SIGNATURE"
Response 200
{
  "id": 52331,
  "object": "withdrawal",
  "amount": 1050,
  "api_key_id": 42,
  "currency": "EUR",
  "external_id": "PAYOUT-2026-0001",
  "iban": "SK3112000000198742637541",
  "idempotency_key": null,
  "status": "canceled",
  "metadata": {},
  "statement_descriptor": "Payout for order 1001",
  "created_at": 1759744800,
  "nonce": "UmY4RHNBMXFXZTRUeVU2aQ",
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "name": "John Doe",
    "email": "[email protected]",
    "phone": null,
    "note": null
  },
  "signature": "a081cef2ee4a03b0ca0cad61d02fc315e9254c848bf79cfec586357fdc8c6b1d"
}

Parameters

withdrawal_id requiredpath · integer

Withdrawal ID

Example 52331
Digest requiredheader · string

SHA-256= followed by the Base64 SHA-256 of the exact request body (of an empty body when there is none)

Example SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
X-JWS-Signature requiredheader · string

Detached JWS (<protected header>..<signature>) over the Digest value, made with your QSEAL key. The protected header carries x5t#S256 (QSEAL thumbprint) and sigT (signing time, at most 5 minutes off).

Example eyJhbGciOiJQUzI1NiIsIng1dCNTMjU2IjoiLi4uIn0..c2lnbmF0dXJl

Response 200

One of:

Option 1

idinteger

Withdrawal ID

Example 52331
objectstring

Object type

Example withdrawal
amountinteger

Amount in cents

Example 1050
api_key_idinteger | null

ID of the API key that created the withdrawal, null if it was not created through the API

Example 42
currencystring

Currency code by ISO 4217

Example EUR
external_idstring | null

Your reference for the withdrawal

Example PAYOUT-2026-0001
ibanstring

IBAN of the recipient

Example SK3112000000198742637541
idempotency_keystring | null

Idempotency-Key header of the request that created the withdrawal

Example 7c9e6679-7425-40de-944b-e07fc1f90ae7
statusstring

Withdrawal status

  • pendingCreated, not sent to the bank (or, for a card refund, to the acquirer) yet. Withdrawals held because they exceed your account's withdrawal limits are also pending. Only pending withdrawals can be cancelled.
  • in_transitSent to the bank, waiting for the bank to execute it
  • paidExecuted by the bank (confirmed by the bank or found on Payout's bank statement); for a card refund, confirmed by the acquirer
  • canceledCancelled before it was executed, by you or by Payout. The amount and fees are returned to your available balance. Spelled canceled; checkouts use cancelled.
  • failedRejected by the bank or could not be executed. The amount and fees are returned to your available balance.
metadataobject

Additional data Payout stores with the withdrawal. Empty for withdrawals created through the API.

Example {}
statement_descriptorstring | null

Text for the recipient's bank statement

Example Payout for order 1001
created_atinteger

Timestamp (Unix time in seconds)

Example 1759744800
noncestring

Random string Payout generates for the response signature

Example VGc1SGpLMm1OYjdWY1gzeg
customerobject

Recipient details

Show 6 child attributesHide child attributes
first_namestring

Customer first name

Max length 255 · Example John
last_namestring

Customer surname

Max length 255 · Example Doe
namestring

Customer full name. Can be sent instead of first_name and last_name; responses always contain it.

Example John Doe
emailstring

Customer email

Max length 255 · Example [email protected]
phonestring | null

Customer phone number. Characters other than digits and + are removed.

Example +421900000000
notestring | null

Note about the customer

signaturestring

Response signature, see How to verify the signature

Example 46d36aad1153a6195e6a1db51d0d49d2008acc5c264562b5da30c40e355ce71c

Option 2

allowedboolean

Always false

Example false
statusstring

Current status of the withdrawal

  • pendingCreated, not sent to the bank (or, for a card refund, to the acquirer) yet. Withdrawals held because they exceed your account's withdrawal limits are also pending. Only pending withdrawals can be cancelled.
  • in_transitSent to the bank, waiting for the bank to execute it
  • paidExecuted by the bank (confirmed by the bank or found on Payout's bank statement); for a card refund, confirmed by the acquirer
  • canceledCancelled before it was executed, by you or by Payout. The amount and fees are returned to your available balance. Spelled canceled; checkouts use cancelled.
  • failedRejected by the bank or could not be executed. The amount and fees are returned to your available balance.

Other responses

401

Missing, invalid or expired bearer token.

Example
{
  "errors": "Unauthorized access. Check your token."
}
403

The QWAC or the QSEAL signature was not accepted, for example the certificate is not approved or belongs to another account, Digest does not match the body, or sigT is more than 5 minutes off

Example
{
  "errors": "Forbidden"
}
404

Withdrawal not found, or not the mTLS host

POST

Check if cancellable

/api/v2/withdrawals/{withdrawal_id}/cancel_allowed on api-mtls-sandbox.payout.one · api-mtls.payout.one

Tells whether Cancel withdrawal would succeed now. Like the read-only requests, it needs the bearer token and the QWAC, no QSEAL signature.

Request
curl -X POST 'https://api-mtls-sandbox.payout.one/api/v2/withdrawals/52331/cancel_allowed' \
  --cert qwac.pem --key qwac.key \
  -H "Authorization: Bearer $TOKEN"
Response 200
{
  "allowed": true
}

Parameters

withdrawal_id requiredpath · integer

Withdrawal ID

Example 52331

Response 200

allowedboolean

Whether Cancel withdrawal would succeed now

Example true

Other responses

401

Missing, invalid or expired bearer token.

Example
{
  "errors": "Unauthorized access. Check your token."
}
403

No approved QWAC presented in the TLS handshake, the certificate belongs to another account, or the withdrawal belongs to another account

Example
{
  "errors": "Forbidden"
}
404

Withdrawal not found, or not the mTLS host

GET

List payment methods

/api/v1/payment_methods

Lists the payment methods enabled for your account, with their fees. Send an identificator as payment_method in Create checkout to open that method for the customer.

Request
curl -X GET 'https://sandbox.payout.one/api/v1/payment_methods' \
  -H "Authorization: Bearer $TOKEN"
Response 200
[
  {
    "name": "Card Payment",
    "identificator": "card",
    "fixed_fee": 20,
    "percentual_fee": 1.5
  },
  {
    "name": "Bank transfer",
    "identificator": "bank_transfer",
    "fixed_fee": 10,
    "percentual_fee": 0.0
  }
]

Response 200 · array

namestring

Payment method name

Example Card Payment
identificatorstring

Payment method identifier. All card payment methods share the identifier card; other methods have their own, for example pisp or bank_transfer.

Example card
fixed_feeinteger

Fixed fee per payment in cents

Example 20
percentual_feenumber

Percentage fee (1.5 = 1.5 %) of the payment amount

Example 1.5

Other responses

401

Missing, invalid or expired bearer token.

Example
{
  "errors": "Unauthorized access. Check your token."
}
GET

Retrieve balance

/api/v1/balance

Returns the balance of the account your API key belongs to, one entry per currency.

Request
curl -X GET 'https://sandbox.payout.one/api/v1/balance' \
  -H "Authorization: Bearer $TOKEN"
Response 200
[
  {
    "available": 25500,
    "currency": "USD",
    "pending": 0
  },
  {
    "available": 1567243,
    "currency": "EUR",
    "pending": 14768
  }
]

Response 200 · array

availableinteger

Money you can withdraw or refund from, in cents. Released incoming payments minus withdrawals, refunds, chargebacks and fees.

Example 1567243
pendinginteger

Incoming payments in cents (after fees) that are not released to available yet. They are not part of available.

Example 14768
currencystring

Currency code by ISO 4217

Example EUR

Other responses

401

Missing, invalid or expired bearer token.

Example
{
  "errors": "Unauthorized access. Check your token."
}
POST

Import certificate

/api/v1/mtls/certificates

Imports a QWAC or QSEAL certificate for the server-to-server APIs, such as M2M withdrawals. Upload the PEM-encoded certificate only, never the private key. The certificate must be issued by a QTSP in Payout's trust store.

The certificate starts in status pending until Payout verifies it manually. See mTLS client certificates.

Request
curl -X POST 'https://sandbox.payout.one/api/v1/mtls/certificates' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
       "type": "qwac",
       "pem": "-----BEGIN CERTIFICATE-----\nMIIF...\n-----END CERTIFICATE-----\n"
     }'
Response 201
{
  "thumbprint": "103a697b2fddcad32f63b842fbe48dd47eaf70340edb6df2e6677c7b70889a57",
  "type": "qwac",
  "status": "pending",
  "issuer_dn": "C=SK,O=Example QTSP,CN=Example Qualified CA",
  "subject_dn": "C=SK,O=Example s.r.o.,organizationIdentifier=NTRSK-12345678,CN=Example s.r.o.",
  "subject_org_id": "NTRSK-12345678",
  "valid_from": "2026-06-09T06:23:06Z",
  "valid_until": "2027-06-09T06:23:06Z"
}

Request body

type requiredstring

Certificate profile

  • qwacClient certificate presented in the TLS handshake on the mTLS host
  • qsealSeal certificate whose key signs the X-JWS-Signature header
Example qwac
pem requiredstring

PEM-encoded certificate

Example -----BEGIN CERTIFICATE----- MIIF... -----END CERTIFICATE-----

Response 201

thumbprintstring

SHA-256 fingerprint of the certificate (lowercase hex)

Example 103a697b2fddcad32f63b842fbe48dd47eaf70340edb6df2e6677c7b70889a57
typestring

Certificate profile

  • qwacClient certificate presented in the TLS handshake on the mTLS host
  • qsealSeal certificate whose key signs the X-JWS-Signature header
Example qwac
statusstring

Approval status of the certificate

  • pendingImported, waiting for manual verification by Payout
  • approvedVerified by Payout and accepted until valid_until
  • rejectedRejected or revoked by Payout, see rejection_reason
issuer_dnstring

Issuer distinguished name

Example C=SK,O=Example QTSP,CN=Example Qualified CA
subject_dnstring

Subject distinguished name

Example C=SK,O=Example s.r.o.,organizationIdentifier=NTRSK-12345678,CN=Example s.r.o.
subject_org_idstring | null

Value of the organizationIdentifier subject attribute

Example NTRSK-12345678
valid_fromstring<date-time>

Start of the certificate's validity (notBefore)

Example 2026-06-09T06:23:06Z
valid_untilstring<date-time>

End of the certificate's validity (notAfter). After it, the certificate is no longer accepted.

Example 2027-06-09T06:23:06Z
rejection_reasonstring | null

Reason of rejection, if the certificate was rejected

validated_atstring<date-time> | null

When Payout approved or rejected the certificate

Other responses

401

Missing, invalid or expired bearer token.

Example
{
  "errors": "Unauthorized access. Check your token."
}
409

A certificate with the same thumbprint is already imported

Example
{
  "errors": {
    "thumbprint": "certificate already imported"
  }
}
422

Malformed PEM, untrusted issuer, or missing or invalid type / pem

Example
{
  "errors": {
    "pem": "invalid"
  }
}
GET

List certificates

/api/v1/mtls/certificates

Lists the certificates imported for your account, newest first.

Request
curl -X GET 'https://sandbox.payout.one/api/v1/mtls/certificates' \
  -H "Authorization: Bearer $TOKEN"
Response 200
{
  "data": [
    {
      "thumbprint": "103a697b2fddcad32f63b842fbe48dd47eaf70340edb6df2e6677c7b70889a57",
      "type": "qwac",
      "status": "approved",
      "subject_dn": "C=SK,O=Example s.r.o.,organizationIdentifier=NTRSK-12345678,CN=Example s.r.o.",
      "valid_until": "2027-06-09T06:23:06Z"
    }
  ]
}

Response 200

dataobject[]

Your certificates, newest first

Show 5 child attributesHide child attributes
thumbprintstring

SHA-256 fingerprint of the certificate (lowercase hex)

Example 103a697b2fddcad32f63b842fbe48dd47eaf70340edb6df2e6677c7b70889a57
typestring

Certificate profile

  • qwacClient certificate presented in the TLS handshake on the mTLS host
  • qsealSeal certificate whose key signs the X-JWS-Signature header
Example qwac
statusstring

Approval status of the certificate

  • pendingImported, waiting for manual verification by Payout
  • approvedVerified by Payout and accepted until valid_until
  • rejectedRejected or revoked by Payout, see rejection_reason
subject_dnstring

Subject distinguished name

Example C=SK,O=Example s.r.o.,organizationIdentifier=NTRSK-12345678,CN=Example s.r.o.
valid_untilstring<date-time>

End of the certificate's validity (notAfter). After it, the certificate is no longer accepted.

Example 2027-06-09T06:23:06Z

Other responses

401

Missing, invalid or expired bearer token.

Example
{
  "errors": "Unauthorized access. Check your token."
}
GET

Retrieve certificate status

/api/v1/mtls/certificates/{thumbprint}/status

Returns the approval status of one of your certificates. The certificate can be used once its status is approved.

Request
curl -X GET 'https://sandbox.payout.one/api/v1/mtls/certificates/103a697b2fddcad32f63b842fbe48dd47eaf70340edb6df2e6677c7b70889a57/status' \
  -H "Authorization: Bearer $TOKEN"
Response 200
{
  "thumbprint": "103a697b2fddcad32f63b842fbe48dd47eaf70340edb6df2e6677c7b70889a57",
  "status": "pending"
}

Parameters

thumbprint requiredpath · string

SHA-256 fingerprint of the certificate (lowercase hex), as returned on import

Example 103a697b2fddcad32f63b842fbe48dd47eaf70340edb6df2e6677c7b70889a57

Response 200

thumbprintstring

SHA-256 fingerprint of the certificate (lowercase hex)

Example 103a697b2fddcad32f63b842fbe48dd47eaf70340edb6df2e6677c7b70889a57
statusstring

Approval status of the certificate

  • pendingImported, waiting for manual verification by Payout
  • approvedVerified by Payout and accepted until valid_until
  • rejectedRejected or revoked by Payout, see rejection_reason
rejection_reasonstring | null

Reason of rejection, if the certificate was rejected

Other responses

401

Missing, invalid or expired bearer token.

Example
{
  "errors": "Unauthorized access. Check your token."
}
404

Certificate not found (or not owned by your account)

Example
{
  "errors": "certificate not found"
}
DELETE

Delete certificate

/api/v1/mtls/certificates/{thumbprint}

Deletes one of your certificates. It can no longer be used for M2M withdrawals.

Request
curl -X DELETE 'https://sandbox.payout.one/api/v1/mtls/certificates/103a697b2fddcad32f63b842fbe48dd47eaf70340edb6df2e6677c7b70889a57' \
  -H "Authorization: Bearer $TOKEN"

Parameters

thumbprint requiredpath · string

SHA-256 fingerprint of the certificate (lowercase hex), as returned on import

Example 103a697b2fddcad32f63b842fbe48dd47eaf70340edb6df2e6677c7b70889a57

Responses

204

Certificate deleted

401

Missing, invalid or expired bearer token.

Example
{
  "errors": "Unauthorized access. Check your token."
}
404

Certificate not found (or not owned by your account)

Example
{
  "errors": "certificate not found"
}

Was this page helpful?