curl --request POST \
  --url https://api.kemycard.com/v1/payouts/beneficiaries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_code": "019abc12-3456-7890-abcd-ef0123456789",
  "type": "individual",
  "name": "JANE DOE",
  "bank_name": "Test Bank",
  "iban": "DE89370400440532013000",
  "bic_swift": "COBADEFFXXX",
  "street": "1 Test Street",
  "city": "Berlin",
  "state_province": "BE",
  "postal_code": "10115",
  "country": "DE"
}
'

{
  "success": true,
  "data": {
    "code": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "customer_code": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "type": "individual",
    "name": "JANE DOE",
    "bank_name": "Test Bank",
    "iban_masked": "DE89 **** 3000",
    "bic_swift": "COBADEFFXXX",
    "address": {
      "street": "1 Test Street",
      "city": "Berlin",
      "state_province": "BE",
      "postal_code": "10115",
      "country": "DE"
    },
    "rail": "sepa",
    "created_at": "2023-11-07T05:31:56Z"
  },
  "meta": {
    "request_id": "a4f8e2c1b3d97056",
    "mode": "test",
    "timestamp": "2023-11-07T05:31:56Z"
  }
}

Payouts

Create a Beneficiary

Saves the bank account of a beneficiary for one of your customers. Only a customer with verification_level verified or full and status active can have beneficiaries.

rail selects the kind of bank account:

sepa (default): bank account in a SEPA country, paid in EUR by SEPA Instant. The full iban is required and must belong to the selected country. state_province must be a value returned by GET /payouts/countries for that country. Responses only return the masked IBAN.
us: bank account in the United States, paid in USD by ACH. Send account_type, account_number, routing_number (9-digit ABA routing number, its check digit is verified), the bank’s address (bank_street, bank_city, bank_state, bank_postal_code) and the account holder’s address in the United States (street, city, state_province, postal_code). bank_state and state_province must be value fields returned by GET /payouts/countries for US. Responses only return the last 4 digits of the account number (account_number_masked).

A customer can have up to 50 active beneficiaries. The same IBAN, or the same US bank account (routing number and account number), cannot be saved twice for a customer.

POST

payouts

beneficiaries

curl --request POST \
  --url https://api.kemycard.com/v1/payouts/beneficiaries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_code": "019abc12-3456-7890-abcd-ef0123456789",
  "type": "individual",
  "name": "JANE DOE",
  "bank_name": "Test Bank",
  "iban": "DE89370400440532013000",
  "bic_swift": "COBADEFFXXX",
  "street": "1 Test Street",
  "city": "Berlin",
  "state_province": "BE",
  "postal_code": "10115",
  "country": "DE"
}
'

{
  "success": true,
  "data": {
    "code": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "customer_code": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "type": "individual",
    "name": "JANE DOE",
    "bank_name": "Test Bank",
    "iban_masked": "DE89 **** 3000",
    "bic_swift": "COBADEFFXXX",
    "address": {
      "street": "1 Test Street",
      "city": "Berlin",
      "state_province": "BE",
      "postal_code": "10115",
      "country": "DE"
    },
    "rail": "sepa",
    "created_at": "2023-11-07T05:31:56Z"
  },
  "meta": {
    "request_id": "a4f8e2c1b3d97056",
    "mode": "test",
    "timestamp": "2023-11-07T05:31:56Z"
  }
}

Authorizations

Authorization

string

header

required

API key (sk_test_... or sk_live_...)

Body

application/json

SEPA beneficiary (EUR)
US beneficiary (ACH, USD)

customer_code

string<uuid>

required

Code of the customer (verified or full, status active)

name

string

required

Name of the account holder

Maximum string length: 140

Example:

"JANE DOE"

bank_name

string

required

Maximum string length: 140

Example:

"Test Bank"

iban

string

required

Full IBAN, spaces allowed. Must belong to country.

Example:

"DE89370400440532013000"

bic_swift

string

required

Example:

"COBADEFFXXX"

street

string

required

Maximum string length: 200

Example:

"1 Test Street"

city

string

required

Maximum string length: 100

Example:

"Berlin"

state_province

string

required

A value returned by GET /payouts/countries for this country

Example:

"BE"

postal_code

string

required

Maximum string length: 20

Example:

"10115"

country

string

required

Country of the bank account (ISO 3166-1 alpha-2), one of GET /payouts/countries

Example:

"DE"

rail

enum<string>

default:sepa

sepa (default when omitted): bank account in a SEPA country, paid in EUR

Available options:

sepa

type

enum<string>

default:individual

individual for a person, business for a company

Available options:

individual,

business

Response

Beneficiary created

success

boolean

Example:

true

data

SEPA beneficiary · object

SEPA beneficiary
US beneficiary (ACH)

Show child attributes

Overview

Customers

Card Products

Cards

KYC

POA

Wallets

Virtual Accounts

Gift Cards

Payouts

Balance

Webhooks

Create a Beneficiary

Authorizations

Body

Response