Payouts

Get the field requirements for a payout corridor

Returns what a payout into a corridor requires of both parties: the beneficiary fields and the senderInfo keys that must and may be provided, reported for an individual and for a business of each party so a caller never has to declare one type to learn the other. Pass route (and, for mobile money or SWIFT, country) to narrow the answer to one corridor; without them it is combined across every rail serving the currency, so satisfying it satisfies the most demanding one. For the recipient it also reports the rules a field value must satisfy, such as an individual name that must split into a first and a last name, as a pattern to validate against before submitting. Each rule is enforced at submit with a 400 naming the field and carrying a stable code; without route, a combined rule is enforced only where the provider that pays out applies it.

GET

payouts

requirements

curl --request GET \
  --url https://api.example.com/v2/payouts/requirements \
  --header 'Authorization: Bearer <token>'

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

fetch('https://api.example.com/v2/payouts/requirements', 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/v2/payouts/requirements",
  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/v2/payouts/requirements"

	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/v2/payouts/requirements")

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

{
  "beneficiary": {
    "business": {
      "optional": [
        "email",
        "addressLine2",
        "countrySubdivision",
        "dateOfBirth"
      ],
      "required": [
        "address",
        "city",
        "postcode"
      ],
      "rules": [
        {
          "description": "An individual recipient needs a first and a last name, separated by a space.",
          "field": "name",
          "pattern": "^[^\\S ]*\\S[^ ]* \\s*\\S[\\s\\S]*$"
        }
      ]
    },
    "individual": {
      "optional": [
        "email",
        "addressLine2",
        "countrySubdivision",
        "dateOfBirth"
      ],
      "required": [
        "address",
        "city",
        "postcode"
      ],
      "rules": [
        {
          "description": "An individual recipient needs a first and a last name, separated by a space.",
          "field": "name",
          "pattern": "^[^\\S ]*\\S[^ ]* \\s*\\S[\\s\\S]*$"
        }
      ]
    }
  },
  "sender": {
    "business": {
      "optional": [
        "dateOfBirth",
        "address",
        "postalCode",
        "city",
        "country",
        "phoneNumber",
        "fundOrigin",
        "gender"
      ],
      "required": [
        "firstName",
        "lastName"
      ]
    },
    "individual": {
      "optional": [
        "dateOfBirth",
        "address",
        "postalCode",
        "city",
        "country",
        "phoneNumber",
        "fundOrigin",
        "gender"
      ],
      "required": [
        "firstName",
        "lastName"
      ]
    },
    "senderInfoRequired": false
  }
}

{
  "details": [
    {
      "field": "accounts.0.data",
      "message": "crAccount must be exactly 10 digits for Nigerian accounts"
    }
  ],
  "error": "BAD_REQUEST",
  "message": "crAccount must be exactly 10 digits for Nigerian accounts",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Authorizations

Authorization

string

header

required

Enter Auth0 JWT token

Query Parameters

currency

string

required

Destination currency (e.g. NGN, EUR, USD, GBP)

Pattern: ^[A-Za-z]{3,10}$

Example:

"EUR"

route

enum<string>

The rail the payout will take, as sent on POST /v1/payouts. Narrows both parties to the rules of that corridor: without it the answer is combined across every rail serving the currency, so satisfying it satisfies the most demanding one.

Available options:

sepa_inst,

sepa_credit,

bank_transfer,

ach,

fedwire,

swift,

crypto,

mobile_money

Example:

"swift"

country

string

An ISO 3166-1 alpha-2 country code. With route=mobile_money it is the destination country, and narrows rules that apply to one country of a currency, such as the sender phone a mobile-money payout into Cameroon carries. With route=swift it is the beneficiary's country, which decides the provider that pays out and so the recipient rules that apply. Ignored on any other rail, and ignored when no route is named.

Pattern: ^[A-Za-z]{2}$

Example:

"CM"

Response

Field requirements for both parties of a payout into the corridor

beneficiary

object

required

What the recipient must and may carry, for each recipient type: the fields that must and may be provided, and the rules their values must satisfy, such as a corridor that addresses an individual recipient by first and last name separately.

Show child attributes

sender

object

required

What the originator must and may carry, for each sender type, and whether senderInfo can be omitted at all.

Show child attributes

Get the field requirements for a payout corridor

curl --request GET \
  --url https://api.example.com/v2/payouts/requirements \
  --header 'Authorization: Bearer <token>'

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

fetch('https://api.example.com/v2/payouts/requirements', 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/v2/payouts/requirements",
  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/v2/payouts/requirements"

	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/v2/payouts/requirements")

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

{
  "beneficiary": {
    "business": {
      "optional": [
        "email",
        "addressLine2",
        "countrySubdivision",
        "dateOfBirth"
      ],
      "required": [
        "address",
        "city",
        "postcode"
      ],
      "rules": [
        {
          "description": "An individual recipient needs a first and a last name, separated by a space.",
          "field": "name",
          "pattern": "^[^\\S ]*\\S[^ ]* \\s*\\S[\\s\\S]*$"
        }
      ]
    },
    "individual": {
      "optional": [
        "email",
        "addressLine2",
        "countrySubdivision",
        "dateOfBirth"
      ],
      "required": [
        "address",
        "city",
        "postcode"
      ],
      "rules": [
        {
          "description": "An individual recipient needs a first and a last name, separated by a space.",
          "field": "name",
          "pattern": "^[^\\S ]*\\S[^ ]* \\s*\\S[\\s\\S]*$"
        }
      ]
    }
  },
  "sender": {
    "business": {
      "optional": [
        "dateOfBirth",
        "address",
        "postalCode",
        "city",
        "country",
        "phoneNumber",
        "fundOrigin",
        "gender"
      ],
      "required": [
        "firstName",
        "lastName"
      ]
    },
    "individual": {
      "optional": [
        "dateOfBirth",
        "address",
        "postalCode",
        "city",
        "country",
        "phoneNumber",
        "fundOrigin",
        "gender"
      ],
      "required": [
        "firstName",
        "lastName"
      ]
    },
    "senderInfoRequired": false
  }
}

{
  "details": [
    {
      "field": "accounts.0.data",
      "message": "crAccount must be exactly 10 digits for Nigerian accounts"
    }
  ],
  "error": "BAD_REQUEST",
  "message": "crAccount must be exactly 10 digits for Nigerian accounts",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}