Home > Cookbooks > Make simple payments to beneficiaries

Make simple payments to beneficiaries

A payment is a transfer of money from a payer’s account to a beneficiary.

Payments cannot be made in one currency and received in another. To pay a beneficiary in a particular currency, the payer must hold funds in that currency. If necessary, the payer must convert funds from one currency to another before making a payment.

In this cookbook, you will:

• 1. Check how much money you hold in various foreign currencies.
• 2. Use funds from your Euros balance to make a payment in Euros to a beneficiary in Germany.

Step 1: Login

Please refer to the Authentication cookbook for instructions to start a new API session.

Step 2: Check available balances

To find out how many Euros you have, call the Get Balance endpoint, passing EUR as the third URI path parameter.

GET /v2/balances/EUR
X-Auth-Token: ea6d13c7bc50feb46cf978d137bc01a2

The following response shows that you hold €15,458.12 in your main Currencycloud account.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "ad6411db-1e00-44fd-b4e8-194c74cf2f83",
  "account_id": "d22073a6-4c56-4980-8699-504b0c70003f",
  "currency": "EUR",
  "amount": "15458.12",
  "created_at": "2018-12-10T16:05:20+00:00",
  "updated_at": "2018-12-10T16:05:20+00:00"
}

Alternatively, you can check the balances for all foreign currencies that you hold in your Currencycloud account by calling the Find Balances endpoint.

GET /v2/balances/find
X-Auth-Token: ea6d13c7bc50feb46cf978d137bc01a2

The following response shows that you hold £10,750.00, US$1,500.24 and €15,458.12 in your main Currencycloud account.

{
  "balances": [
    {
      "id": "c52128a4-3918-40dc-a92a-7225cef3a4a6",
      "account_id": "d22073a6-4c56-4980-8699-504b0c70003f",
      "currency": "GBP",
      "amount": "10750.00",
      "created_at": "2018-12-10T16:05:19+00:00",
      "updated_at": "2018-12-10T16:05:19+00:00"
    },
    {
      "id": "349a2b87-9455-4808-9e68-515daf1f7298",
      "account_id": "d22073a6-4c56-4980-8699-504b0c70003f",
      "currency": "USD",
      "amount": "1550.24",
      "created_at": "2018-12-10T16:05:19+00:00",
      "updated_at": "2018-12-10T16:05:19+00:00"
    },
    {
      "id": "ad6411db-1e00-44fd-b4e8-194c74cf2f83",
      "account_id": "d22073a6-4c56-4980-8699-504b0c70003f",
      "currency": "EUR",
      "amount": "15458.12",
      "created_at": "2018-12-10T16:05:20+00:00",
      "updated_at": "2018-12-10T16:05:20+00:00"
    }
  ],
  "pagination": {
    "total_entries": 3,
    "total_pages": 1,
    "current_page": 1,
    "per_page": 25,
    "previous_page": -1,
    "next_page": -1,
    "order": "created_at",
    "order_asc_desc": "asc"
  }
}

Step 3: Check payment requirements

Currencycloud supports two types of payments:

• 1. Regular payments: Made using the local bank network. Regular payments are normally received by beneficiary’s within five working days of the settlement date. This is a good choice for low-value, non-urgent transactions.
• 2. Priority payments: Made using the SWIFT network. Payments can be made to over 212 countries, and 95% of payments arrive within one working day.

You want to make a regular payment to a supplier based in Germany. You will pay the beneficiary in Euros. You have enough funds in your Euros balance already to make this payment, so there is no need to top-up your Euros balance beforehand.

First, check what details are required to make a regular payment in Euros to a beneficiary with a bank account in Germany. To do that, call the Get Beneficiary Requirements endpoint.

GET /v2/reference/beneficiary_required_details

The following response tells us that, to make a regular payment to a German bank account in Euros, we need two pieces of information: the IBAN and BIC/SWIFT numbers for the beneficiary. The beneficiary could be either a company or an individual. Either way, the same information is required.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "details": [
    {
      "payment_type": "priority",
      "beneficiary_entity_type": "individual",
      "beneficiary_address": "^.{1,255}",
      "beneficiary_city": "^.{1,255}",
      "beneficiary_country": "^[A-z]{2}$",
      "beneficiary_first_name": "^.{1,255}",
      "beneficiary_last_name": "^.{1,255}",
      "iban": "([A-Z0-9]\\s*){15,34}",
      "bic_swift": "^[0-9A-Z]{8}$|^[0-9A-Z]{11}$"
    },
    {
      "payment_type": "priority",
      "beneficiary_entity_type": "company",
      "beneficiary_address": "^.{1,255}",
      "beneficiary_city": "^.{1,255}",
      "beneficiary_country": "^[A-z]{2}$",
      "beneficiary_company_name": "^.{1,255}",
      "iban": "([A-Z0-9]\\s*){15,34}",
      "bic_swift": "^[0-9A-Z]{8}$|^[0-9A-Z]{11}$"
    },
    {
      "payment_type": "regular",
      "iban": "([A-Z0-9]\\s*){15,34}",
      "bic_swift": "^[0-9A-Z]{8}$|^[0-9A-Z]{11}$",
      "beneficiary_entity_type": "individual"
    },
    {
      "payment_type": "regular",
      "iban": "([A-Z0-9]\\s*){15,34}",
      "bic_swift": "^[0-9A-Z]{8}$|^[0-9A-Z]{11}$",
      "beneficiary_entity_type": "company"
    }
  ]
}

Step 4: Add a beneficiary

If you know the required details, you can go ahead and create a record for the beneficiary via the Create Beneficiary endpoint.

POST /v2/beneficiaries/create
Content-Type: multipart/form-data

If the beneficiary is successfully created, the response message will contain full details about the beneficiary as recorded in your Currencycloud account. Note the beneficiary’s unique ID (id). You’ll need this to make a payment to the beneficiary, in the next step.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "aea097c2-39e4-49b5-aaa6-c860ca55ca0b",
  "bank_account_holder_name": "Acme GmbH",
  "name": "Acme GmbH",
  "email": null,
  "payment_types": [
    "regular"
  ],
  "beneficiary_address": [],
  "beneficiary_country": "DE",
  "beneficiary_entity_type": null,
  "beneficiary_company_name": null,
  "beneficiary_first_name": null,
  "beneficiary_last_name": null,
  "beneficiary_city": null,
  "beneficiary_postcode": null,
  "beneficiary_state_or_province": null,
  "beneficiary_date_of_birth": null,
  "beneficiary_identification_type": null,
  "beneficiary_identification_value": null,
  "bank_country": "DE",
  "bank_name": "Test Bank Plc",
  "bank_account_type": null,
  "currency": "EUR",
  "account_number": null,
  "routing_code_type_1": null,
  "routing_code_value_1": null,
  "routing_code_type_2": null,
  "routing_code_value_2": null,
  "bic_swift": "COBADEFF",
  "iban": "DE89370400440532013000",
  "default_beneficiary": "false",
  "creator_contact_id": "1993263d-be07-42d4-b75b-ae4ea18bcb6c",
  "bank_address": [],
  "created_at": "2018-02-02T11:52:23+00:00",
  "updated_at": "2018-02-02T11:52:23+00:00",
  "beneficiary_external_reference": null
}

Step 5: Make a payment

Authorize a payment by calling the Create Payment endpoint. Optionally, you may provide an idempotency key (via the unique_request_id parameter). This helps protect against accidental duplicate payments.

POST /v2/payments/create
Content-Type: multipart/form-data

If the payment is successfully queued, the response payload will contain all the information about the payment as recorded in your Currencycloud account. This does not mean that the payment was made. It just means that it is ready for processing.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "bea05ec4-8c6b-4ec9-80e5-65c0cd257473",
  "amount": "10000.00",
  "beneficiary_id": "aea097c2-39e4-49b5-aaa6-c860ca55ca0b",
  "currency": "EUR",
  "reference": "2018-014",
  "reason": "Invoice Payment",
  "status": "ready_to_send",
  "creator_contact_id": "1993263d-be07-42d4-b75b-ae4ea18bcb6c",
  "payment_type": "regular",
  "payment_date": "2018-02-02",
  "transferred_at": "",
  "authorisation_steps_required": "0",
  "last_updater_contact_id": "1993263d-be07-42d4-b75b-ae4ea18bcb6c",
  "short_reference": "180202-RDRWGQ001",
  "conversion_id": null,
  "failure_reason": "",
  "payer_id": "49d44eff-af91-45b0-a32e-84c7c1750ca0",
  "payer_details_source": "account",
  "created_at": "2018-02-02T11:56:05+00:00",
  "updated_at": "2018-02-02T11:56:05+00:00",
  "payment_group_id": null,
  "unique_request_id": "4abd730f-bb50-4b4a-8890-f46addff222b",
  "failure_returned_amount": "0.00",
  "ultimate_beneficiary_name": null
}

Payments are processed first-in, first-out. Currencycloud will process payments on the payment_date specified, provided you hold enough money in the relevant currency at the time.