Payout (Asynchronous)

Initiate an asynchronous payout to send funds to a cardholder. A webhook will be sent to the specified notificationUrl once processed.

We recommend a minimum timeout of 5 seconds.

Initiate an asynchronous payout to send funds to a cardholder. A webhook will be sent to the specified notificationUrl once processed. *We recommend a minimum timeout of 5 seconds.*

Authorization

BearerAuth

AuthorizationBearer <token>

In: header

Header Parameters

Idempotency-Keystring

If a response is replayed due to using the same key, the response will include the header Idempotent-Replayed: true.

Idempotency keys are scoped by [Key, Endpoint, HTTP Verb]; the same key on a different endpoint or method will not replay the original response.

Responses are cached for 24 hours. After that, the cache is cleared, so idempotency is only guaranteed within 24 hours of the initial request.

Ensures that a request can be safely retried without causing duplicate operations. Typically used for actions like payment creation and operations such as refund and void to prevent accidental double processing. - If a response is replayed due to using the same key, the response will include the header `Idempotent-Replayed: true`. - Idempotency keys are scoped by **[Key, Endpoint, HTTP Verb]**; the same key on a different endpoint or method will not replay the original response. - Responses are cached for **24 hours**. After that, the cache is cleared, so idempotency is only guaranteed within 24 hours of the initial request.

Request Body

application/json

Payout request payload.

TypeScript Definitions

Use the request body type in TypeScript.

pointOfSaleIdstring

Required

UUID of the Point of Sale to debit from; must belong to your account.

Format:

uuid

Example:

"0192473a-e381-705c-b61c-fc2ac9624afc"

amountinteger

Required

Amount in minor units (e.g., 1095 = 10.95 DKK). Must be >= 1.

Range:

1 <= value

Example:

1000

currencystring

Required

ISO 4217 alpha-3 currency, e.g., “DKK”.

Match:

^[A-Z]{3}$

Example:

"DKK"

paymentMethodIdstring

Required

UUID of a stored payment method eligible for payouts.

Format:

uuid

Example:

"01924756-d1f6-738d-8040-90d76cedf01f"

referencestring

Merchant reference for reconciliation; should be unique per payout when possible. Defaults to the ePay transaction id.

Example:

"payout-1"

textOnStatementstring

Descriptor shown on recipient’s statement; acquirer limits may apply (e.g., 22 chars).

Length:

1 <= length <= 39

Example:

"Prize money"

DEPRECATED: This parameter will soon be removed and will no longer have any effect. The functionality has been replaced by routing rules in the ePay back office.

List of permitted processors; order is priority fallback. Values: shift4, clearhaus, nets.

**DEPRECATED:** *This parameter will soon be removed and will no longer have any effect. The functionality has been replaced by routing rules in the ePay back office.* List of permitted processors; order is priority fallback. Values: shift4, clearhaus, nets.

Example:

[
  "shift4",
  "clearhaus"
]

[index]Processor

Identifier of a payment processor. This value determines which payment gateway(s) are used to process a payment.

Possible values:

"shift4""clearhaus""nets""worldline"

Pass-through key-value pairs returned in webhooks; recommend max combined size (e.g., 1 KB) and ASCII/UTF-8 guidance.

Example:

{
  "key1": "value1",
  "key2": "value2"
}

[key: string]unknown

firstNamestring

Required

Recipient name; used for compliance and risk.

Example:

"Morten"

lastNamestring

Required

Recipient name; used for compliance and risk.

Example:

"Thomassen"

ipstring

Required

IPv4/IPv6 address of the client initiating the payout request; used for fraud/risk.

Example:

"118.249.219.99"

The birthdate of the recipient. YYYY-MM-DD; required by some payout methods;

Match:

^\d{4}-\d{2}-\d{2}$

Example:

"1970-01-01"

notificationUrlstring

Required

Webhook target for payout result. This endpoint will be called once the transaction is fully processed.

Format:

uri

Response Body

`application/json`

curl -X POST "https://example.com/public/api/v1/payout" \  -H "Idempotency-Key: c4f5e8d2-1234-5678-90ab-cdef12345678" \  -H "Content-Type: application/json" \  -d '{    "pointOfSaleId": "0192473a-e381-705c-b61c-fc2ac9624afc",    "amount": 1000,    "currency": "DKK",    "paymentMethodId": "01924756-d1f6-738d-8040-90d76cedf01f",    "notificationUrl": "https://example.com/notification",    "reference": "payout-1",    "textOnStatement": "Prize money",    "processor": [      "shift4",      "clearhaus"    ],    "attributes": {      "key1": "value1",      "key2": "value2"    },    "customer": {      "firstName": "Morten",      "lastName": "Thomassen",      "ip": "118.249.219.99",      "birthdate": "1970-01-01"    }  }'

{  "transaction": {    "id": "LDG7M4WW44G",    "subscriptionId": "0197c07b-3f6d-7be2-b848-702b08958128",    "billingAgreementChargeId": "019a727b-987f-7768-a59e-71af920ef81f",    "state": "PENDING",    "errorCode": "string",    "externalStatusCodes": {      "terminal": "string",      "acquirer": "string",      "network": "string",      "sca": "string"    },    "createdAt": "2019-08-24T14:15:22Z",    "sessionId": "string",    "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011",    "paymentMethodType": "CARD",    "paymentMethodSubType": "Visa",    "paymentMethodExpiry": "2019-08-24",    "paymentMethodDisplayText": "string",    "paymentMethodHolderName": "string",    "scaMode": "SKIP",    "customerId": "string",    "amount": 0,    "fee": 0,    "currency": "string",    "instantCapture": "OFF",    "notificationUrl": "http://example.com",    "pointOfSaleId": "be6bff4f-7fac-43c0-9f6b-cf2cd45ed7d1",    "reference": "string",    "textOnStatement": "string",    "exemptions": [      "LVT",      "TRA"    ],    "attributes": {      "property1": null,      "property2": null    },    "clientIp": "52.212.176.122",    "clientCountry": "DK",    "type": "PAYMENT"  }}

{  "errorCode": "SERVER_ERROR",  "message": "An unexpected system error"}

{  "errorCode": "VALIDATION_ERROR",  "message": "Input validation errors",  "errors": {    "amount": [      "[required]: Is a required non-nullable field",      "[int]: Must be an integer",      "[min:0]: Must be greater than 0",      "[max:999999999]: Must be less than 999999999"    ]  }}

{  "errorCode": "SERVER_ERROR",  "message": "An unexpected system error"}

Authorization

Header Parameters

Request Body

Response Body

200application/json

400application/json

422application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`