NAV Navbar

API Reference

Welcome to the Verify Payments API 👋! The reference documentation below describes the various functions that you can use to initiate, track and manage fiat transfers using the Verify Payments API.

All endpoints described below can be run in Postman with our collection of requests. We also have a configured Postman environment for the provided collection. You can download it here and then import it into the Postman app.

Run in Postman

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "%api_endpoint%/" \
  -H "Authorization: Token %test_secret_key%"

The code above actually works. You can paste it directly in your terminal to try it out!

You can authenticate requests to the Verify Payments API by including your public key or secret key in the request that you send, depending on the endpoint. Each endpoint will indicate which key it expects from you. We currently use Token authentication without the underlying OAuth 2.0 protocol.

The private keys used to authenticate with the API are generated through the Dashboard — keep these private! Make sure not to commit them to your source code repositories or share them.

Include the API key for all requests to the server in a header that looks like the following: Authorization: Token "%test_secret_key%"

All API calls must be made using HTTPS. Calls made over unsecured HTTP connections will fail.

Banks

Before the user can sign in to their bank, they must select one from a list of supported banks.

The bank object

{
  "id": "test_bank",
  "object": "bank",
  "name": "Test Bank"
}

Parameters

Parameter Description
id The unique ID of this specific bank
object The type of the object (always bank for Banks)
name The name of the bank in user-readable form

List all banks

Example Request:

curl %api_endpoint%/banks \
  -H "Authorization: Token %test_public_key%"

HTTP Request

GET %api_endpoint%/banks

Query Parameters

This endpoint does not require any parameters

Example Response:

[
  {
    "id": "test_bank",
    "name": "Test Bank",
    "object": "bank"
  }
]

Sessions

A Session represents a connection with a customers bank account. An active session must exist beforer a Transfer can be initiated.

The session object

{
  "id": "ses_pvhOgYMSNPpM",
  "object": "session",
  "status": "initial",
  "created_at": "2018-08-19T10:10:43.612Z",
  "updated_at": "2018-08-19T10:10:43.612Z"
}

Parameters

Parameter Description
id The unique ID of this specific session
object The type of the object (always session for Sessions)
status The status of the session. Can be either initial, pending_verification, connected, failed or completed

Create a session

Example Request:

curl "%api_endpoint%/sessions/" \
  -H "Authorization: Token %test_secret_key%" \
  -d "currency=AED" \
  -d "amount=10000" \
  -d "description=My First Session"

HTTP Request

POST %api_endpoint%/sessions/

Example Response:

{
  "id": "ses_rDCKbNpZhfzF",
  "object": "session",
  "status": "initial",
  "created_at": "2018-08-19T10:50:28.297Z",
  "updated_at": "2018-08-19T10:50:28.297Z"
}

URL Parameters

Parameter Description
currency The 3-letter ISO4217 currency code for the transfer that you will create after this session is established
amount The transfer amount, in fils (e.g. 1000 = AED10.00)
description A desciption that can be included on the checkout screen shown to the user

Login to a session

Once a session is created, we then have to authenticate the session by calling the login endpoint, making sure to include the id of the session that we're referring to in the request URL.

Example Request:

curl "%api_endpoint%/sessions/<id>/login" \
  -H "Authorization: Token %test_public_key%" \
  -d "bank_id=test_bank" \
  -d "credentials[login]=test" \
  -d "credentials[password]=test_pass"

HTTP Request

POST %api_endpoint%/sessions/<id>/login

Example Response:

{
  "id": "ses_2Ocvnws4y3Yr",
  "object": "session",
  "status": "connected",
  "created_at": "2018-08-19T12:21:34.784Z",
  "updated_at": "2018-08-19T12:21:51.757Z",
}

URL Parameters

Parameter Description
bank_id The ID of the Bank that the user will attempt to login to
credentials A hash containing the online banking credentials supplied by the user, for authentication. This should include a login and password field containing the respective values

Retrieve a session

Example Request:

curl "%api_endpoint%/sessions/<id>" \
  -H "Authorization: Token %test_secret_key%"

Example Response:

{
  "id": "ses_rDCKbNpZhfzF",
  "object": "session",
  "status": "initial",
  "created_at": "2018-08-19T10:50:28.297Z",
  "updated_at": "2018-08-19T10:50:28.297Z"
}

Retrieves the details of a session.

HTTP Request

POST %api_endpoint%/sessions/<id>

Bank Accounts

Once a session has been established, you can retrieve a list of Bank Accounts that the account owner can choose from when performing the transfer.

The Bank Account object

{
  "id": "ba_kEUWd9qXlyCx",
  "object": "bank_account",
  "bank_id": "test_bank",
  "iban": "AE070331234567890123456",
  "number": "1234567890123456",
  "type": "current",
  "currency": "AED",
  "balance": 1000,
  "session_id": "ses_2Ocvnws4y3Yr"
}

Parameters

Parameter Description
id The unique ID of this specific bank account. Note that this ID is unique to the current session
object The type of the object (always bank_account for Bank Accounts)
bank_id The Bank that this account belongs to
iban The IBAN is an alphanumeric string of up to 34 characters that uniquely identifies account numbers globally
number The account number. Exact length varies by bank and type of account
type The type of this account (either current or savings)
currency The 3-letter ISO4217 currency code for this bank account
balance The account balance, in fils
session_id Identifies the session that this bank account belongs to

List all bank accounts

Example Request:

curl "%api_endpoint%/sessions/<id>/bank_accounts" \
  -X GET \
  -H "Authorization: Token %test_public_key%"

HTTP Request

GET %api_endpoint%/sessions/<id>/bank_accounts

Example Response:

[
  {
    "balance": 1000,
    "bank_id": "test_bank",
    "currency": "AED",
    "iban": "AE070331234567890123456",
    "id": "ba_kEUWd9qXlyCx",
    "number": "1234567890123456",
    "object": "bank_account",
    "session_id": "ses_2Ocvnws4y3Yr",
    "type": "current"
  },
  {
    "balance": 1000,
    "bank_id": "test_bank",
    "currency": "USD",
    "iban": "AE070331234567890123457",
    "id": "ba_4yiusVJdVxqC",
    "number": "1234567890123457",
    "object": "bank_account",
    "session_id": "ses_2Ocvnws4y3Yr",
    "type": "savings"
  },
  {
    "balance": 1000,
    "bank_id": "test_bank",
    "currency": "BHD",
    "iban": "AE070331234567890123458",
    "id": "ba_l5uF4BMbTh4L",
    "number": "1234567890123458",
    "object": "bank_account",
    "session_id": "ses_2Ocvnws4y3Yr",
    "type": "savings"
  }
]

Parameters

This endpoint does not require any parameters

Transfers

A Transfer object represents an instruction to move funds from the source account of the authenticated customer to the merchants account.

The Transfer object

{
  "id": "tr_F2sqeKZa8ppl",
  "object": "transfer",
  "bank_id": "test_bank",
  "source_id": "ba_l5uF4BMbTh4L",
  "status": "pending_verification",
  "amount": 100,
  "currency": "BHD",
  "description": "NA",
  "verification": {
    "attempt_count": 0,
    "challenge_text": "Please, enter test OTP (1234 to finish or 12345 for one more verification)",
    "id": "vrf_gWHiYgmdX6cM",
    "object": "verification",
    "status": "initial",
    "type": "sms",
    "verifiable_id": "tr_F2sqeKZa8ppl",
    "verifiable_type": "transfer"
  },
  "session_id": "ses_2Ocvnws4y3Yr",
  "created_at": "2018-08-19T15:27:15.502Z",
  "updated_at": "2018-08-19T15:27:15.607Z"
}

Parameters

Parameter Description
id The unique ID of this specific transfer
object The type of the object (always transfer for Transfers)
bank_id The Bank that this transfer originates from
source_id The Bank Account that will fund this transfer
status The status of this transfer. Can be either initial, succeeded, pending_verification or failed
amount The transfer amount, in fils. This is set when the session object is created
currency The 3-letter ISO4217 currency code for this bank account
description A description that can be used to describe the purpose of the transfer
verification A Verification object
session_id Identifies the session that this bank account belongs to
reference_id Identifies the id of the transfer on the bank side

Create a Transfer

Example Request:

curl "%api_endpoint%/sessions/<id>/transfers" \
  -H "Authorization: Token %test_public_key%" \
  -d "source=ba_kEUWd9qXlyCx"

HTTP Request

POST %api_endpoint%/sessions/<id>/transfers

Example Response:

{
  "id": "tr_F2sqeKZa8ppl",
  "object": "transfer",
  "bank_id": "test_bank",
  "source_id": "ba_l5uF4BMbTh4L",
  "status": "pending_verification",
  "amount": 100,
  "currency": "BHD",
  "description": "NA",
  "verification": {
    "attempt_count": 0,
    "challenge_text": "Please, enter test OTP (1234 to finish or 12345 for one more verification)",
    "id": "vrf_gWHiYgmdX6cM",
    "object": "verification",
    "status": "initial",
    "type": "sms",
    "verifiable_id": "tr_F2sqeKZa8ppl",
    "verifiable_type": "transfer"
  },
  "session_id": "ses_2Ocvnws4y3Yr",
  "created_at": "2018-08-19T15:27:15.502Z",
  "updated_at": "2018-08-19T15:27:15.607Z",
  "reference_id":"TRANSFERa003d0398779da23f6a37c80d24e9e0c"
}

Parameters

Parameter Description
source
Required
The Bank Account that will be used to fund the transfer. You can retrieve a list of all bank accounts for the authenticated user here.

Retrieve a transfer

Example Request:

curl "%api_endpoint%/sessions/<id>/transfers/<transfer_id>" \
  -H "Authorization: Token %test_secret_key%"

Example Response:

{
  "object":"transfer",
  "id":"tr_F2sqeKZa8ppl",
  "amount":100,
  "currency":"BHD",
  "description":"Test transfer",
  "status":"succeeded",
  "session_id":"ses_2Ocvnws4y3Yr",
  "bank_id":"test_bank",
  "source_id":"ba_l5uF4BMbTh4L",
  "created_at": "2018-08-19T15:27:15.502Z",
  "updated_at": "2018-08-19T15:27:15.607Z"
  "reference_id":"TRANSFERa003d0398779da23f6a37c80d24e9e0c"
}

Retrieves the details of a transfer.

HTTP Request

POST %api_endpoint%/sessions/<id>/transfers/<transfer_id>

List all session transfers

Example Request:

curl "%api_endpoint%/sessions/<id>/transfers" \
  -X GET \
  -H "Authorization: Token %test_public_key%"

HTTP Request

GET %api_endpoint%/sessions/<id>/transfers

Example Response:

[
  {
    "object":"transfer",
    "id":"tr_F2sqeKZa8ppl",
    "amount":100,
    "currency":"BHD",
    "description":"Test transfer",
    "status":"succeeded",
    "session_id":"ses_2Ocvnws4y3Yr",
    "bank_id":"test_bank",
    "source_id":"ba_l5uF4BMbTh4L",
    "created_at": "2018-08-19T15:27:15.502Z",
    "updated_at": "2018-08-19T15:27:15.607Z"
    "reference_id":"TRANSFERa003d0398779da23f6a37c80d24e9e0c"
  }
]

Parameters

This endpoint does not require any parameters

Verifications

Creating a Session or Transfer can sometimes require additional verification by our banking providers. There are currently 2 supported methods for verification:

Verification Type Description
sms An SMS code is sent to the registered mobile device and the account owner is requested to provide the numeric code
questions The banking provider returns question(s) and the account owner is requested to supply the answers to these questions

The specific verification method required will depend on several things including the bank that a transfer is initiated from and whether a transfer has previously been completed from this customers' account.

The verification object

{
  "id": "vrf_zGf5ZH3LzXDz",
  "object": "verification",
  "type": "sms",
  "status": "initial",
  "verifiable_id": "ses_2Ocvnws4y3Yr",
  "verifiable_type": "session",
  "attempt_count": 0,
  "challenge_text": "Please, enter test OTP (1234 to finish or 12345 for one more verification)"
}

Parameters

Parameter Description
id The unique ID of this verification
object The type of the object (always verification for Verifications)
type The method of verification required (either sms or questions)
status The status of the verification. Can be either initial, retry, succeeded or failed
challenge_text A human-friendly text that can be displayed to the account owner in your custom UI
verifiable_type The Type of the object that this verification is for. Can either be transfer or session
verifiable_id The ID of the Transfer or Session to which this verification belongs
attempt_count The number of times this verification has been attempted

Submit a verification

Example Request:

curl "%api_endpoint%/sessions/<id>/verifications/<id>" \
  -X PUT \
  -H "Authorization: Token %test_public_key%" \
  -d "challenge_response=12345"

Submit the challenge_response or answers[] for a verification. This request is idempotent, and you can safely submit the request multiple times.

HTTP Request

PUT /sessions/<id>/verifications/<id> or PUT /transfers/<id>/verifications/<id>

Example Response:

{
  "id": "vrf_zGf5ZH3LzXDz",
  "object": "verification",
  "type": "sms",
  "attempt_count": 1,
  "challenge_text": "Please, enter test OTP (1234 to finish or 12345 for one more verification)",
  "status": "succeeded",
  "verifiable_id": "ses_2Ocvnws4y3Yr",
  "verifiable_type": "session",
  "verifiable": {
    "id": "ses_2Ocvnws4y3Yr",
    "object": "session",
    "status": "pending_verification",
    "verification": {
      "id": "vrf_ZhNRoP5eLx60",
      "object": "verification",
      "status": "initial",
      "type": "questions",
      "questions": [
          "What is your favorite language (ruby)",
          "What is your favorite editor (vim)"
      ],
      "attempt_count": 0,
      "verifiable_id": "ses_2Ocvnws4y3Yr",
      "verifiable_type": "session"
    },
    "created_at": "2018-08-19T12:21:34.784Z",
    "updated_at": "2018-08-19T13:49:51.688Z"
  }
}

Parameters

Parameter Description
challenge_response
Optional
The response provided by the customer to the sms verification challenge (e.g. "12345")
answers[]
Optional
The response provided by the customer to the questions verification challenge. This is an array (e.g. ["first", "second"])