Get payout by ID

GET

payouts

{id}

Get payout by ID

curl --request GET \
  --url https://api.example.com/v1/payouts/{id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.example.com/v1/payouts/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/payouts/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/payouts/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/payouts/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "amount": "100.50",
  "beneficiary": {
    "accounts": [
      {
        "createdAt": "2024-01-15T10:30:00Z",
        "currency": "EUR",
        "data": {
          "bic": "DEUTDEFF",
          "iban": "DE89370400440532013000"
        },
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "status": "active",
        "type": "iban",
        "updatedAt": "2024-01-15T10:35:00Z"
      }
    ],
    "createdAt": "2024-01-15T10:30:00Z",
    "email": "john.doe@example.com",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "John Doe",
    "status": "active",
    "updatedAt": "2024-01-15T10:35:00Z"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "currency": "EUR",
  "fee": "2.50",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "route": "international",
  "status": "processing",
  "type": "fiat",
  "updatedAt": "2024-01-15T10:35:00Z",
  "accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "balanceAfter": "98.87",
  "clientRef": "PAYOUT-REF-12345",
  "completedAt": "2024-01-15T10:40:00Z",
  "description": "Payment for services rendered",
  "failureCategory": "payment_not_approved",
  "failureReason": "Insufficient funds",
  "fxRate": "970.87378641",
  "inputAmount": "1.13",
  "inputCurrency": "EUR",
  "payoutAccountData": {
    "account": 123456789,
    "bankCode": "044",
    "crAccount": "0123456789"
  },
  "payoutAccountId": "123e4567-e89b-12d3-a456-426614174000",
  "processedAt": "2024-01-15T10:32:00Z",
  "providerReference": "TXN123456789",
  "quoteId": "123e4567-e89b-12d3-a456-426614174000",
  "reference": "January invoice",
  "txHash": "0x3a1f9c2b4d5e6f70819a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f70",
  "uetr": "4afd0a57-03af-4138-9341-373a78891ea9"
}

{
  "error": "insufficient_scope",
  "message": "API key is missing required scope: read:payouts",
  "path": "/v1/resource",
  "requiredScope": "read:payouts",
  "statusCode": 403,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Authorizations

Authorization

string

header

required

Enter Auth0 JWT token

Path Parameters

string<uuid>

required

Unique identifier for the payout

Example:

"123e4567-e89b-12d3-a456-426614174000"

Response

Payout found

amount

string

required

Amount of the payout (as string to avoid floating-point precision issues)

Example:

"100.50"

beneficiary

object

required

Beneficiary information

Show child attributes

Example:

{
  "accounts": [
    {
      "createdAt": "2024-01-15T10:30:00Z",
      "currency": "EUR",
      "data": {
        "bic": "DEUTDEFF",
        "iban": "DE89370400440532013000"
      },
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "active",
      "type": "iban",
      "updatedAt": "2024-01-15T10:35:00Z"
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "email": "john.doe@example.com",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "John Doe",
  "status": "active",
  "updatedAt": "2024-01-15T10:35:00Z"
}

createdAt

string<date-time>

required

Creation timestamp

Example:

"2024-01-15T10:30:00Z"

currency

enum<string>

required

Currency code (ISO 4217). Default enabled currencies: EUR, USD, GBP, USDC, EURC, NGN. Contact your account manager to enable additional currencies.

Available options:

EUR,

USD,

GBP,

USDC,

USDT,

EURC,

NGN,

XOF,

XAF,

GHS,

KES,

UGX,

MZN

Example:

"EUR"

fee

string

required

Fee charged for the payout (as string to avoid floating-point precision issues)

Example:

"2.50"

string<uuid>

required

Unique identifier for the payout

Example:

"123e4567-e89b-12d3-a456-426614174000"

route

string

required

Client-facing payment rail. Provider names are never exposed; a provider-routed transfer reads as a generic rail (e.g. international).

Example:

"international"

status

enum<string>

required

Current status of the payout

Available options:

created,

queued,

processing,

paid,

failed,

cancelled,

awaiting_approval,

approval_expired,

approval_rejected,

awaiting_funding

Example:

"processing"

type

enum<string>

required

Type of payout

Available options:

fiat,

crypto

Example:

"fiat"

updatedAt

string<date-time>

required

Last update timestamp

Example:

"2024-01-15T10:35:00Z"

accountId

string<uuid>

The sub-account the payout was made on behalf of. Absent when the client paid from its own balance.

balanceAfter

string

Account balance after this transaction (in input currency, e.g., EUR)

Example:

"98.87"

clientRef

string

Client-supplied idempotency reference provided at payout creation. Stable across retries and the natural lookup key for support / reconciliation. Absent on provider-synthesized DTOs (e.g. webhook callbacks) where the original client ref is not in scope.

Maximum string length: 100

Example:

"PAYOUT-REF-12345"

completedAt

string<date-time>

Completion timestamp

Example:

"2024-01-15T10:40:00Z"

description

string

Description of the payout

Example:

"Payment for services rendered"

failureCategory

enum<string>

Category of failure for client-facing display

Available options:

payment_not_approved,

recipient_details,

amount_issue,

technical_error

Example:

"payment_not_approved"

failureReason

string

Reason for failure if payout failed

Example:

"Insufficient funds"

fxRate

string

FX rate applied, with markup. On a payout priced from a held quote (quoteId set) it is inputCurrency units per one unit of the destination currency; otherwise it is destination units per one unit of inputCurrency (e.g. 970.87 NGN per EUR).

Example:

"970.87378641"

inputAmount

string

Input amount (total amount charged to the client including fee, in input currency)

Example:

"1.13"

inputCurrency

enum<string>

Input currency (the currency debited from the client account). This is determined by the inputCurrency provided in the request, or automatically selected as the currency with the largest available balance, or defaults to USD. For example, EUR when paying out NGN. Default enabled currencies: EUR, USD, GBP, USDC, EURC, NGN. Contact your account manager to enable additional currencies.

Available options:

EUR,

USD,

GBP,

USDC,

USDT,

EURC,

NGN,

XOF,

XAF,

GHS,

KES,

UGX,

MZN

Example:

"EUR"

payoutAccountData

object

Payout account data (JSONB)

Example:

{
  "account": 123456789,
  "bankCode": "044",
  "crAccount": "0123456789"
}

payoutAccountId

string<uuid>

Payout account ID

Example:

"123e4567-e89b-12d3-a456-426614174000"

processedAt

string<date-time>

Processing start timestamp

Example:

"2024-01-15T10:32:00Z"

providerReference

string

Reference from the payment provider

Example:

"TXN123456789"

quoteId

object | null

The held quote that priced this payout, and null when it was priced at send from the current rate. Optional because a release that predates the field omits it: treat an absent key as unknown rather than as priced-at-send, since on that release every cross-currency payout was quote-priced.

Example:

"123e4567-e89b-12d3-a456-426614174000"

reference

string

Optional free-text memo/narration that appears on the recipient side. Use clientRef for idempotency / support lookups.

Example:

"January invoice"

txHash

string | null

On-chain transaction hash for crypto payouts, once the transfer is broadcast to the network. Null for non-crypto payouts or before broadcast.

Example:

"0x3a1f9c2b4d5e6f70819a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f70"

uetr

string | null

SWIFT UETR (Unique End-to-end Transaction Reference) for SWIFT payouts, once the provider exposes it. Null otherwise.

Example:

"4afd0a57-03af-4138-9341-373a78891ea9"

Get payout by ID

curl --request GET \
  --url https://api.example.com/v1/payouts/{id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.example.com/v1/payouts/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/payouts/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/payouts/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/payouts/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "amount": "100.50",
  "beneficiary": {
    "accounts": [
      {
        "createdAt": "2024-01-15T10:30:00Z",
        "currency": "EUR",
        "data": {
          "bic": "DEUTDEFF",
          "iban": "DE89370400440532013000"
        },
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "status": "active",
        "type": "iban",
        "updatedAt": "2024-01-15T10:35:00Z"
      }
    ],
    "createdAt": "2024-01-15T10:30:00Z",
    "email": "john.doe@example.com",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "John Doe",
    "status": "active",
    "updatedAt": "2024-01-15T10:35:00Z"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "currency": "EUR",
  "fee": "2.50",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "route": "international",
  "status": "processing",
  "type": "fiat",
  "updatedAt": "2024-01-15T10:35:00Z",
  "accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "balanceAfter": "98.87",
  "clientRef": "PAYOUT-REF-12345",
  "completedAt": "2024-01-15T10:40:00Z",
  "description": "Payment for services rendered",
  "failureCategory": "payment_not_approved",
  "failureReason": "Insufficient funds",
  "fxRate": "970.87378641",
  "inputAmount": "1.13",
  "inputCurrency": "EUR",
  "payoutAccountData": {
    "account": 123456789,
    "bankCode": "044",
    "crAccount": "0123456789"
  },
  "payoutAccountId": "123e4567-e89b-12d3-a456-426614174000",
  "processedAt": "2024-01-15T10:32:00Z",
  "providerReference": "TXN123456789",
  "quoteId": "123e4567-e89b-12d3-a456-426614174000",
  "reference": "January invoice",
  "txHash": "0x3a1f9c2b4d5e6f70819a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f70",
  "uetr": "4afd0a57-03af-4138-9341-373a78891ea9"
}

{
  "error": "insufficient_scope",
  "message": "API key is missing required scope: read:payouts",
  "path": "/v1/resource",
  "requiredScope": "read:payouts",
  "statusCode": 403,
  "timestamp": "2024-01-15T10:30:00.000Z"
}