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.

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

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"]`)

Notice — A verification may return another verification. Check the status of the included verifiable object to determine if this is the case

API Reference

Authentication

Banks

The bank object

Parameters

List all banks

HTTP Request

Query Parameters

Sessions

The session object

Parameters

Create a session

HTTP Request

URL Parameters

Login to a session

HTTP Request

URL Parameters

Retrieve a session

HTTP Request

Bank Accounts

The Bank Account object

Parameters

List all bank accounts

HTTP Request

Parameters

Transfers

The Transfer object

Parameters

Create a Transfer

HTTP Request

Parameters

Retrieve a transfer

HTTP Request

List all session transfers

HTTP Request

Parameters

Verifications

The verification object

Parameters

Submit a verification

HTTP Request

Parameters