How to Add Global Payments to Your Code with Currencycloud's APIs

Every company makes payments, even if they're not in finance. The speed in which this money moves can either impede or accelerate new opportunities and growth for a business.

Currencycloud is a cloud payments platform that allows businesses to automate and send international bank transfers. Developers can use Currencycloud's APIs to incorporate payment capabilities into applications and their user experiences.

In this guide, you'll learn how to use the Currencycloud APIs so you can begin to make international payments from within your business applications.

Getting set up

First, let's discuss some best practices. While the documentation is freely accessible, you should register for a Currencycloud API key so you can immediately access the API sandbox, which is a great place to experiment with the API.

One thing to keep in mind is your business use case for accessing the payment API — whether it's for currency exchange, payments to employees, settlements with clients, all of the above, or other use cases.

1. Register for the API
Begin by requesting access to the API by clicking the "register for demo API key" button in the Developer Center. This will prompt you to create your unique demo login and set up account security.

2. Familiarize yourself with the documentation
Once you're plugged in, look through the online API documentation, which details how each API call works.

3. Start building the sandbox environment to make payments Develop and build against the APIs in the sandbox environment. Keep in mind that the demo API is connected to a test infrastructure. Although it returns real data, trades are executed in a demo "market" and cannot dispatch real payments.

How Currencycloud's APIs Work — The Payment Service Provider

Let's say your business provides airline passengers with flight compensation for delayed, cancelled, or overbooked flights when traveling into and out of the European Union. You collect these funds from the airlines themselves with payouts to the passengers.

In the process of building your business, you've attracted a large number of American passengers who are looking to get compensated for European flights. You're looking to automate those payments to alleviate your team of operational processes, save on exchange rates and payment fees from banks, and guarantee that the full amount of funds gets to your customers.

In this section, you'll learn how to convert from euros to U.S. dollars and then make a payment for $700.

For the purposes of this demo, you'll be using the cURL command line utility for interacting with the Currencycloud's API endpoint. CURL is built into all Unix and Linux-based systems, such as OS X and Ubuntu, and it can be downloaded for Windows. Be sure to enter the cURL commands that appear in this tutorial at the command prompt of your operating system.

1. Authenticate
To access the API call, you first need to authenticate with your Currencycloud login ID and API key. Your login id and key (retrievable from the Currencycloud Developer Portal when you're logged in) will be different than the ones that appear below.

Request

curl -X POST -d "login_id=apitester" -d "api_key=99b0d6895f95e46d9eaf5c85aa0f64dca9007b7ab0778721b6cdc0a8bc7c56cf" https://devapi.currencycloud.com/v2/authenticate/api

If the login is successful, an authorization token like the one below will be returned. Add this token to the HTTP header for all other subsequent API requests.

Response

{"auth_token": "ea6d13c7bc50feb46cf978d137bc01a2"}

2. Convert
Let's assume you're happy with the EURO/USD real-time rate indicated by Currencycloud and now wish to complete a conversion of 700 euros (the currency you're selling) into U.S. dollars (the currency you're buying). Try the following cURL command with your authorization token (you can omit the backslashes if you put it all on one line):

curl -X POST \
--header "X-Auth-Token: ea6d13c7bc50feb46cf978d137bc01a2" \
-d "buy_currency=USD" \
-d "sell_currency=EUR" \
-d "amount=700.00" \
-d "fixed_side=buy" \
-d "reason=Passenger Reimbursement" \
-d "term_agreement=true" \
https://devapi.currencycloud.com/v2/conversions/create

That API call request should yield a (JSON) response similar to the following:

{
  "id": "11441095-87a4-4905-a3a0-cdbe312fc02e",
  "settlement_date": "2017-02-06T14:00:00+00:00",
  "conversion_date": "2017-02-06T00:00:00+00:00",
  "short_reference": "20170206-RKJZDL",
  "creator_contact_id": "3b9878d3-ee87-62f8-b35d-4d91d7c34a9a",
  "account_id": "25cd25d1-ae2e-4a50-89cf-1540d0f3e34e",
  "currency_pair": "USDEUR",
  "status": "awaiting_funds",
  "buy_currency": "USD",
  "sell_currency": "EUR",
  "client_buy_amount": "700.00",
  "client_sell_amount": "617.07",
  "fixed_side": "buy",
  "mid_market_rate": "1.1344",
  "core_rate": "1.1341",
  "partner_rate": "",
  "partner_status": "funds_arrived",
  "partner_buy_amount": "0.00",
  "partner_sell_amount": "0.00",
  "client_rate": "1.1341",
  "deposit_required": "false",
  "deposit_amount": "0.00",
  "deposit_currency": "",
  "deposit_status": "not_required",
  "deposit_required_at": "",
  "payment_ids": "[]",
  "created_at": "2017-02-06T12:57:22+00:00",
  "updated_at": "2017-02-06T12:57:22+00:00"
}

A successful response means that the conversion has been executed and the amount of sold currency needs to arrive to Currencycloud by the date and time found in the "settlement_date" field. The bought currency will be available in your Currencycloud account to pay after the amount has cleared on the conversion date. Also, upon close inspection of that JSON response (or any response from Currencycloud involving a transaction), you'll see that the transaction has an "id" field. In this case, because the transaction was a conversion, you can think of the id as a "conversion id." For the purposes of this tutorial, keep track of the conversion id. You'll need it later.

3. Add a beneficiary (the recipient of the funds)
Let's say you want to make a regular payment to the American customer now that the U.S. dollars have arrived. To do this, you first need to check which details are required using the following cURL command with your authorization token:

curl -X GET \
--header "X-Auth-Token: ea6d13c7bc50feb46cf978d137bc01a2" \
-d "currency=USD" \
-d "bank_account_country=US" \
https://devapi.currencycloud.com/v2/reference/beneficiary_required_details

That API call request should yield a response similar to the following JSON.:

{
  "details": [
    {
      "payment_type": "regular",
      "iban": "^[0-9A-Z]{1,34}$",
      "bic_swift": "^[0-9A-Z]{8}$|^[0-9A-Z]{11}$"
    },
    {
      "payment_type": "priority",
      "iban": "^[0-9A-Z]{1,34}$",
      "bic_swift": "^[0-9A-Z]{8}$|^[0-9A-Z]{11}$"
    }
  ]
}
{
    "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}",
            "beneficiary_state_or_province": "^.{1,255}",
            "beneficiary_postcode": "^.{1,255}",
            "acct_number": "^\\d{1,17}$",
            "aba": "^[0-9A-Z]{9}$"
        },
        {
            "payment_type": "priority",
            "beneficiary_state_or_province": "^.{1,255}",
            "beneficiary_postcode": "^.{1,255}",
            "beneficiary_entity_type": "company",
            "beneficiary_address": "^.{1,255}",
            "beneficiary_city": "^.{1,255}",
            "beneficiary_country": "^[A-z]{2}$",
            "beneficiary_company_name": "^.{1,255}",
            "acct_number": "^\\d{1,17}$",
            "aba": "^[0-9A-Z]{9}$"
        },
        {
            "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}",
            "beneficiary_state_or_province": "^.{1,255}",
            "beneficiary_postcode": "^.{1,255}",
            "acct_number": "^\\d{1,17}$",
            "bic_swift": "^[0-9A-Z]{8}$|^[0-9A-Z]{11}$"
        },
        {
            "payment_type": "priority",
            "beneficiary_state_or_province": "^.{1,255}",
            "beneficiary_postcode": "^.{1,255}",
            "beneficiary_entity_type": "company",
            "beneficiary_address": "^.{1,255}",
            "beneficiary_city": "^.{1,255}",
            "beneficiary_country": "^[A-z]{2}$",
            "beneficiary_company_name": "^.{1,255}",
            "acct_number": "^\\d{1,17}$",
            "bic_swift": "^[0-9A-Z]{8}$|^[0-9A-Z]{11}$"
        },
        {
            "payment_type": "regular",
            "beneficiary_address": "^.{1,255}",
            "beneficiary_city": "^.{1,255}",
            "beneficiary_country": "^[A-z]{2}$",
            "beneficiary_entity_type": "individual",
            "beneficiary_first_name": "^.{1,255}",
            "beneficiary_last_name": "^.{1,255}",
            "beneficiary_state_or_province": "^.{1,255}",
            "beneficiary_postcode": "^.{1,255}",
            "aba": "^[0-9A-Z]{9}$",
            "acct_number": "^\\d{1,17}$"
        },
        {
            "payment_type": "regular",
            "beneficiary_address": "^.{1,255}",
            "beneficiary_city": "^.{1,255}",
            "beneficiary_country": "^[A-z]{2}$",
            "beneficiary_entity_type": "company",
            "beneficiary_company_name": "^.{1,255}",
            "beneficiary_state_or_province": "^.{1,255}",
            "beneficiary_postcode": "^.{1,255}",
            "aba": "^[0-9A-Z]{9}$",
            "acct_number": "^\\d{1,17}$"
        }
    ]
}

A close inspection of this JSON reveals that two payment types are offered: "regular" and "priority." Priority is an international wire payment, which is the fastest way to transfer funds, but also the most expensive.

Liam McAndrew Liam is Head of Development at Currencycloud. Having been with the company since its inception he has played a key role in building the technology that has transacted over $25bn worth of payments. He is excited by the emergence of cryptocurrencies and blockchain technology, and looks forward to seeing how the payments landscape continues to shift.
 

Comments