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}}/v1/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

curl --location --request POST '{{baseURL}}/v1/payout' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "remark": "Invoice #INV-2025-08",
  "reason": "Payment for services",
  "quoteId": "a4f7b2c1-ef14-4999-906b-xxxxxxxxxxxxx",
  "recipient": {
    "name": "Max Müller",
    "paymentChannel": "BANK_TRANSFER",
    "currency": "EUR",
    "country": "DE",
    "account": {
      "iban": "DE89370400440532013000",
      "bic": "COBADEFFXXX"
    }
  }
}'

Request Body

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

Field	Type	Description
`remark`	String	Additional note about the transaction.
`reason`	String	Purpose of the transfer (e.g., `Payment for services`).
`quoteId`	String	Unique Quote ID for the payout.
`recipient.name`	String	Full name of the recipient.
`recipient.paymentChannel`	String	Payment method (`BANK_TRANSFER`).
`recipient.currency`	String	ISO currency code (`EUR`).
`recipient.country`	String	ISO country code of a SEPA country (e.g., `DE`).
`recipient.account.iban`	String	International Bank Account Number of the recipient.
`recipient.account.bic`	String	Bank Identifier Code (SWIFT code). Optional for some SEPA banks but recommended.

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",
    "remark": "Invoice #INV-2025-08",
    "reason": "Payment for services",
    "referenceNumber": "UYKLG7SXTNPLF",
    "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": {
      "name": "Max Müller",
      "firstName": "Max",
      "lastName": "Müller",
      "relationship": "BUSINESS_PARTNER",
      "type": "BANK",
      "account": {
        "iban": "DE89370400440532013000",
        "bic": "COBADEFFXXX"
      },
      "paymentChannel": "BANK_TRANSFER",
      "currency": "EUR",
      "country": "DE"
    },
    "created": "2025-08-22T11:02:15.038044",
    "processed": "2025-08-22T11:04:21.712685"
  }
}

Response Breakdown

Field	Type	Description	Example
`message`	String	Status message of the payout creation	`"Transaction created successfully"`
`status`	String	Status of the payout	`"success"`
`data`	Object	Details of the payout transaction
`data.id`	String	Unique ID of the transaction	`"a8b9c7d6-4e5f-1234-abcd-xxxxxxxxxxxxx"`
`data.remark`	String	Remark or note for the payout	`"Gift"`
`data.reason`	String	Reason for the payout	`"Gift"`
`data.referenceNumber`	String	Unique reference number for the payout	`"NGNEURXREF123"`
`data.type`	String	Type of transaction	`"SEND"`
`data.state`	String	State of the payout (`PENDING`, `COMPLETED`, etc.)	`"PENDING"`
`data.quote`	Object	Details of the quote
`data.quote.id`	String	Quote ID	`"2000e048-57a7-4c62-bdc8-xxxxxxxxxxxxx"`
`data.quote.source`	Object	Source currency details
`data.quote.source.currency`	String	Source currency code	`"NGN"`
`data.quote.source.country`	String	Source country code	`"NG"`
`data.quote.source.amount`	Number	Amount sent in source currency	`150000`
`data.quote.target`	Object	Target currency details
`data.quote.target.currency`	String	Target currency code	`"EUR"`
`data.quote.target.country`	String	Target country code	`"DE"`
`data.quote.target.amount`	Number	Amount received in target currency	`200`
`data.quote.rate`	Number	Exchange rate used	`750`
`data.quote.fee`	Object	Fee details
`data.quote.fee.amount`	Number	Fee amount in source currency	`1000`
`data.recipient`	Object	Recipient details
`data.recipient.name`	String	Recipient’s full name	`"Busola Obasanjo"`
`data.recipient.type`	String	Recipient type (`BANK`)	`"BANK"`
`data.recipient.account`	Object	Bank account details
`data.recipient.account.accountNumber`	String	Bank account number	`"222222222"`
`data.recipient.account.sortCode`	String	Sort code of the recipient’s bank	`"11111"`
`data.recipient.account.bankName`	String	Bank name of the recipient	`"Bank Name"`
`data.recipient.paymentChannel`	String	Payment method (`BANK_TRANSFER`)	`"BANK_TRANSFER"`
`data.recipient.currency`	String	Currency code of payout	`"EUR"`
`data.recipient.country`	String	Country code of the recipient	`"DE"`
`data.created`	String	Timestamp when the transaction was created	`"2025-06-11T10:45:00.000000"`
`data.processed`	String \| null	Timestamp when the payout was processed or `null`	`null`

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`	Bad Request	Invalid parameters
`401`	Unauthorized	Invalid API key
`422`	Unprocessable Entity	Invalid quote ID
`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