Beneficiaries

Create a beneficiary

Record a recipients details in the system in order to send them funds.

POST /accounts/customer/create_beneficiary
Headers
Content-Type: application/json
Accept: application/json
Authorization: token {{token value from here}}

Parameters

Parameter Format Length Description
customer_id
Required
string 36 The unique customer profile reference returned to you as part of the create.
Acceptable Characters: a-z A-Z , . – _
first_name
Required
string 0-50 Beneficiaries first name.
Acceptable Characters: a-z A-Z , . – _ ’
middle_name string 0-50 Beneficiaries middle name.
Acceptable Characters: a-z A-Z , . – _ ’
last_name
Required
string 0-50 Beneficiaries last name.
Acceptable Characters: a-z A-Z , . – _ ’
email
Recommended
string 0-50 Beneficiaries email address
Acceptable Characters: 0-9 a-z A-z _ – . @
phone_number
Recommended
string 0-50 Beneficiaries phone number
Acceptable Characters: 0-9 ( ) + –
address
Required
object
number
Recommended
string 1-11 Beneficiaries street number.
Acceptable Characters: a-z A-Z 0-9
refinement string 1-100 The address refinement, may include flat number, house name etc e.g. Suite 2, 4th Floor
Acceptable Characters: a-z A-Z 0-9 , . - _
street
Recommended
string 1-100 Beneficiaries street address.
Acceptable Characters: a-z A-Z 0-9 , . - _
region string 1-100 The state, province, prefecture, or region
Acceptable Characters: a-z A-Z 0-9 , . - _
city
Recommended
string 1-100 Beneficiaries city.
Acceptable Characters: a-z A-Z 0-9 , . - _
postal_code
Recommended
string 1-100 Beneficiaries ZIP or postal code.
Acceptable Characters: a-z A-Z 0-9 , . - _
iso_country
Required
string 3 Beneficiaries country, an ISO 3166 2-character code.
Acceptable Characters: a-z A-Z
account
Required
object
account_number
Required
int 0-9 Beneficiaries bank account number..
Acceptable Characters: 0-9
sort_code
Required
string 0-9 Beneficiaries bank sort code.
Acceptable Characters: 0-9 -
{
"customer_id":"22938286-283a-4594-b21c-afb1bd52d22c",
"first_name":"Steve",
"middle_name":"Anthony",
"last_name":"Jobs",
"email":"example@acquired.com",
"phone":"0876543456",
"address":{
    "number":"44",
    "refinement":"Suite 2, 4th Floor",
    "street":"Baker Street",
    "city":"London",
    "postal_code":"W1U7AL",
    "iso_country":"GB"
},
"account":{
    "account_number":"12345678",
    "sort_code":"123456"
}
},

Response

Parameter Format Length Description
status int 1-2 The outcome of the request.
message string 0-100 Handy text describing the response_code or error for debugging.
beneficiary_id string 36 The unique customer profile reference returned to you as part of the create beneficiary procress.
{
    "status": 1,
    "message": "Success",
    "beneficiary_id": "859f4eef-6a53-4110-8757-371844df8e8c"
}

Query a specific beneficiary

Use this to retrieve details for a specific beneficiary

GET /accounts/beneficiary/{beneficiary_id}
Headers
Content-Type: application/json
Accept: application/json
Authorization: token {{token value from here}}

Response

Parameter Format Length Description
status int 1-2 The outcome of the request.
message string 0-100 Handy text describing the response_code or error for debugging.
data object
customer_id string 36 The unique customer profile reference returned to you as part of the create.
first_name string 0-50 Beneficiaries first name.
middle_name string 0-50 Beneficiaries middle name.
last_name string 0-50 Beneficiaries last name.
email string 0-50 Beneficiaries email address
phone_number string 0-50 Beneficiaries phone number
address object
number string 1-11 Beneficiaries street number.
refinement string 1-100 The address refinement, may include flat number, house name etc e.g. Suite 2, 4th Floor
street
string 1-100 Beneficiaries street address.
city string 1-100 Beneficiaries city.
postal_code string 1-100 Beneficiaries ZIP or postal code.
iso_country string 3 Beneficiaries country, an ISO 3166 2-character code.
account object
account_number int 0-9 Beneficiaries bank account number.
sort_code string 0-9 Beneficiaries bank sort code.
{
    "status": 1,
    "message": "Success",
    "data": {
        "customer_id": "5e865d53-669c-4bbe-be49-09494cffc19d",
        "first_name": "Test",
        "middle_name": "",
        "last_name": "kk",
        "email": "peter@acquired.com",
        "phone": "07928267777",
        "address": {
            "number": "44",
            "refinement": "Suite 44, Flat 2",
            "street": "Baker Street",
            "city": "London",
            "postal_code": "SW4 2DJ",
            "iso_country": "FR"
        },
        "account": {
            "account_number": "12345678",
            "sort_code": "123445"
        }
    }
}

Get a list of beneficiaries

Use this to retrieve multiple records of beneficiary details.

GET /accounts/beneficiaries
Headers
Content-Type: application/json
Accept: application/json
Authorization: token {{token value from here}}

Response

Parameter Format Length Description
status int 1-2 The outcome of the request.
message string 0-100 Handy text describing the response_code or error for debugging.
data object
total int Count of objects in list
list array
beneficiary_id string 36 The unique customer profile reference returned to you as part of the create beneficiary procress.
Acceptable Characters: a-z A-Z , . – _
merchant_customer_id string 36 The unique customer profile reference returned to you as part of the create.
Acceptable Characters: a-z A-Z , . – _
first_name string 0-50 Beneficiaries first name.
Acceptable Characters: a-z A-Z , . – _ ’
middle_name string 0-50 Beneficiaries middle name.
Acceptable Characters: a-z A-Z , . – _ ’
last_name string 0-50 Beneficiaries last name.
Acceptable Characters: a-z A-Z , . – _ ’
email string 0-50 Beneficiaries email address
Acceptable Characters: 0-9 a-z A-z _ – . @
phone string 0-50 Beneficiaries phone number
Acceptable Characters: 0-9 ( ) + –
address object
number string 1-11 Beneficiaries street number.
Acceptable Characters: a-z A-Z 0-9
refinement string 1-100 The address refinement, may include flat number, house name etc e.g. Suite 2, 4th Floor
Acceptable Characters: a-z A-Z 0-9 , . - _
street string 1-100 Beneficiaries street address.
Acceptable Characters: a-z A-Z 0-9 , . - _
city string 1-100 Beneficiaries city.
Acceptable Characters: a-z A-Z 0-9 , . - _
postal_code string 1-100 Beneficiaries ZIP or postal code.
Acceptable Characters: a-z A-Z 0-9 , . - _
iso_country string 3 Beneficiaries country, an ISO 3166 2-character code.
Acceptable Characters: a-z A-Z
account object
account_number int 0-9 Beneficiaries bank account number..
Acceptable Characters: 0-9
sort_code string 0-9 Beneficiaries bank sort code.
Acceptable Characters: 0-9 -
{
"status":1,
"message":"Success",
"data":{
    "total":1,
    "list":[
        {
            "beneficiary_id":"22938286-283a-4594-b21c-afb1bd52d22c",
            "merchant_customer_id":"32938286-283a-4594-b21c-afb1bd52d22c",
            "first_name":"Joe",
            "middle_name":"Anthony",
            "last_name":"Bloggs",
            "email":"example@acquired.com",
            "phone":"0876543456",
            "account":{
            "account_number":"12345678",
            "sort_code":"123456"
            }
        }
    ]
}
}