EUR Payouts

This endpoint allows you to send payouts in EUR to recipients in any SEPA country (e.g., Germany, France, Spain). The request must include the recipient's details, payment method, and a valid quoteId.

Endpoint

POST: {{baseURL}}/v2/payout

Request Details

Headers

Include these headers in your request:

Header	Value	Required
`Content-Type`	`application/json`	✅ Yes
`x-api-key`	`YOUR_API_KEY`	✅ Yes

Request Examples

Here are examples of how to make a EUR payout request in different languages.

curl --location --request POST '{{baseURL}}/v2/payout' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "recipient": {
    "firstName": "Edmund",
    "lastName": "Veum",
    "address": "01676 Damien Fall",
    "type": "BUSINESS",
    "account": {
      "bankName": "Deutsche Bank",
      "address": "89730 Marcelle Vista",
      "swiftCode": "DEUTDEFF",
      "accountNumber": "DE89370400440532013000",
      "branchCode": "100"
    },
    "paymentChannel": "BANK_TRANSFER",
    "currency": "EUR",
    "country": "DE",
    "stored": true
  },
  "quoteId": "a4f7b2c1-ef14-4999-906b-xxxxxxxxxxxxx",
  "reason": "Gift",
  "remark": "Testing"
}'

Request Body Breakdown

The following fields are required when making a EUR payout request.

Field	Type	Description	Required
`quoteId`	String	The unique ID of the quote for this payout.	✅ Yes
`reason`	String	The purpose of the transfer (e.g., `Payment for services`).	✅ Yes
`remark`	String	An optional, additional note about the transaction.	✅ Yes
`recipient`	Object	An object containing all details about the person receiving the funds.	✅ Yes
`recipient.firstName`	String	The first name of the recipient.	✅ Yes
`recipient.lastName`	String	The last name of the recipient.	✅ Yes
`recipient.address`	String	The recipient's residential or business address.	✅ Yes
`recipient.type`	String	The type of recipient. Enum: `INDIVIDUAL`, `BUSINESS`.	✅ Yes
`recipient.paymentChannel`	String	The payment method. Must be `BANK_TRANSFER` for EUR payouts.	✅ Yes
`recipient.currency`	String	The ISO currency code. Must be `EUR`.	✅ Yes
`recipient.country`	String	The recipient's two-letter ISO country code (e.g., `DE`).	✅ Yes
`recipient.stored`	Boolean	A flag indicating whether to save the recipient for future use.	✅ Yes
`recipient.account`	Object	An object containing the recipient's bank account details.	✅ Yes
`recipient.account.bankName`	String	The name of the recipient's bank.	✅ Yes
`recipient.account.address`	String	The address of the recipient's bank branch.	✅ Yes
`recipient.account.swiftCode`	String	The Bank Identifier Code (SWIFT/BIC).	✅ Yes
`recipient.account.accountNumber`	String	The recipient's International Bank Account Number (IBAN).	✅ Yes
`recipient.account.branchCode`	String	The specific branch code for the recipient's bank.	✅ Yes

Success Response (200 OK)

If the payout is successfully created, the API returns the following response:

{
  "message": "Transaction created successfully",
  "status": "success",
  "data": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f1234567890a",
    "reason": "Gift",
    "remark": "Testing",
    "referenceNumber": "EUPAYOUT98765",
    "type": "SEND",
    "state": "COMPLETED",
    "quote": {
      "id": "a4f7b2c1-ef14-4999-906b-xxxxxxxxxxxxx",
      "source": {
        "currency": "USD",
        "country": "US",
        "amount": 108.50
      },
      "target": {
        "currency": "EUR",
        "country": "DE",
        "amount": 100
      },
      "rate": 0.9216,
      "fee": {
        "amount": 3.00
      }
    },
    "recipient": {
      "firstName": "Edmund",
      "lastName": "Veum",
      "address": "01676 Damien Fall",
      "type": "BUSINESS",
      "account": {
        "accountNumber": "DE89...3000",
        "swiftCode": "DEUTDEFF",
        "bankName": "Deutsche Bank",
        "address": "89730 Marcelle Vista",
        "branchCode": "100"
      },
      "paymentChannel": "BANK_TRANSFER",
      "currency": "EUR",
      "country": "DE"
    },
    "created": "2025-09-19T10:15:30.123456Z",
    "processed": "2025-09-19T10:16:45.789101Z"
  }
}

Response Breakdown

This section explains each field returned in a successful response.

Field	Type	Description
`message`	String	A confirmation message indicating the result of the request.
`status`	String	The overall status of the request, e.g., `success`.
`data`	Object	A container for all the transaction data.
`data.id`	String	The unique identifier for this payout transaction.
`data.remark`	String	The remark or note that was provided in the request.
`data.reason`	String	The reason for the payout provided in the request.
`data.referenceNumber`	String	A unique reference number generated for the payout.
`data.type`	String	The type of transaction, e.g., `SEND`.
`data.state`	String	The current state of the payout (`COMPLETED`, `PENDING`, etc.).
`data.quote`	Object	Details of the financial quote used for this payout.
`data.quote.id`	String	The unique ID of the quote.
`data.quote.source.currency`	String	The three-letter currency code of the source funds.
`data.quote.source.country`	String	The two-letter country code of the transaction origin.
`data.quote.source.amount`	Number	The amount of money in the source currency.
`data.quote.target.currency`	String	The three-letter currency code of the target funds.
`data.quote.target.country`	String	The two-letter country code of the destination.
`data.quote.target.amount`	Number	The converted amount that the recipient will receive.
`data.quote.rate`	Number	The exchange rate applied to the transaction.
`data.quote.fee.amount`	Number	The transaction fee, in the source currency.
`data.recipient`	Object	Details of the recipient.
`data.recipient.name`	String	The full name of the recipient.
`data.recipient.firstName`	String	The first name of the recipient.
`data.recipient.lastName`	String	The last name of the recipient.
`data.recipient.relationship`	String	The sender's relationship to the recipient.
`data.recipient.type`	String	The type of recipient entity, e.g., `BANK`.
`data.recipient.account.iban`	String	The recipient's International Bank Account Number.
`data.recipient.account.bic`	String	The recipient's Bank Identifier Code (SWIFT).
`data.recipient.paymentChannel`	String	The payment method used, e.g., `BANK_TRANSFER`.
`data.recipient.currency`	String	The currency received by the recipient.
`data.recipient.country`	String	The country of the recipient.
`data.created`	String	ISO 8601 timestamp of when the transaction was created.
`data.processed`	String	ISO 8601 timestamp of when the transaction was processed.

Payout Transaction States

The payout transaction can have one of the following states:

State	Description
`COMPLETED`	The payout was successfully processed.
`PENDING`	The payout is still being processed.
`FAILED`	The payout failed to process.
`REFUNDED`	The payout has been sent back to sender.

Error Handling

Status Code	Meaning	Example Response
`400`	Insufficient Balance	Insufficient Balance
`401`	Unauthorized	Invalid API key provided.
`403`	Forbidden	IP not whitelisted
`404`	Not Found	The requested endpoint does not exist.
`422`	Unprocessable Entity	Invalid quote ID provided.
`500`	Internal Server Error	An internal error occurred.

Best Practices

✅ Ensure quoteId is valid and linked to an existing quote.
✅ Confirm that the recipient’s bank account number and bank code are correct.
✅ Use a valid API key in the headers.
✅ Handle error responses correctly in your integration.

NGN to NGN NGN to GBP