OpenPayd API

OpenPayd API

OpenPayd API
Getting Started

The OpenPayd API lets you develop custom solutions to manage your organization’s payments. Our API offers an easy integration with all the functionality needed for the modern finance department. By accessing OpenPayd’s core engine through the API, you will be able to manage the entire cash flow from collection to payout.

Sign up for a Sandbox OpenPayd user and start exploring our REST API. If you need assistance following this documentation, contact us at contact@openpayd.com and we will respond as soon as we can.

Environments
Sandbox https://sandbox-api.openpayd.com/api/v1
Production https://api.openpayd.com/api/v1
Authentication

Once you sign up for an OpenPayd, you will receive an apiKey. You can then use your login id and apiKey to authenticate.

POST /authentication/login
POST /authentication/logout
Login
POST /authentication/login

Generates a token to authenticate all calls following login.

Request body

ApiKey and loginId are required for calling the login endpoint.

Object
apiKey
string

Generated after user creates OpenPayd account

loginId
string

Email address used during OpenPayd account signup

Responses

200 OK

Successful login

Body
Object
token
string

The authentication token (x-auth-token) that will be used for all subsequent calls

tfaEnabled
boolean
Example:
false
phoneList
Object
countryId
integer
number
string
type
string
email
string
mobilePhoneVerified
boolean
Example:
false
Example request
Example response

sample login request

curl -X "POST" "https://sandbox-api.openpayd.com/api/v1/authentication/login" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "loginId": "email@code.com",
  "apiKey": "25EC53548E5694299168201EE916029F5300CECF9669ABF496FE385F62B71152"
}'

sample login response

{
    "token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlcm9yQGNvbS5jb20iLCJpbnN0YW5jZUlkIjoiMSIsInJvbGUiOlsiVVNSIiwiQVBJX1VTUiJdLCJjaGFubmVsIjoiQVBJIiwic2Vzc2lvbklkIjoiNWQ1NGMwYWItNWNhMS00OThkLTk5NWYtZDAzMjg2MWFlM2Y1IiwidXNlclR5cGUiOiJDTFUiLCJsb2dpbkV2ZW50SWQiOiIzNzU4NCIsInR5cGUiOiIxIiwiZXhwIjoxNTY1MTgwNjEwLCJ1c2VySWQiOiI1NDMiLCJpYXQiOjE1NjUxNzcwMTB9._RcwGz1ClWc4Rj-q1UD0zOQOICKrAja9W115lwmmmDybJ2AhzLq9XgHZ_lUE2L3FYyj5sDnGDUYtbcfuFe--Mg",
    "tfaEnabled": false,
    "tfaType": null,
    "phoneList": null,
    "email": null,
    "mobilePhoneVerified": false
}
Logout
POST /authentication/logout

Perform this call to manually end the session. Alternatively, the user can wait for the session to time out.

Request headers

x-auth-token
string required

Authorization token that was returned from the login call

Responses

200 OK
Example request

sample logout request

curl -X "POST" "https://sandbox-api.openpayd.com/api/v1/authentication/logout" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'
HTTP Request

The following HTTP header will be included in all requests after login.

x-auth-token
string required

The token returned from the login call.

HTTP Response codes
Code Description
200 Request succeeded.
400 Bad request, request is not well-formed or syntactically incorrect.
401 Authentication failure. Verify that the authorization token is correct.
500 Internal server error, although the client provided a correct request the server experienced a problem.
Postman Collection
You may grab our Postman collection and try calling our OpenPayd api by clicking the “Run in Postman” button.
REST API
Currency Account

Once the OpenPayd user is authenticated, a currency account can be created by calling the /currency-accounts endpoint.

POST /currency-accounts
GET /currency-accounts
GET /currency-accounts/{currency}
GET /currency-accounts/balance-history
GET /pay-ins/{id}
GET /pay-ins
Create a currency account
POST /currency-accounts

Creates a currency account of a given currency for the authenticated OpenPayd user.

Request parameters

currency
string required

Three letter currency code

onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

Responses

200 OK
Body
Object
currency
string

Three letter currency code

status
string
Enumeration:
active
inactive
balance
string

Currency account balance

bankName
string

Bank name used for deposit (pay-in)

bankAccountHolderName
string

Account holder name

accountNumber
string

Account number

bicSwift
string

Swift Number for the bank account

iban
string

Iban for the bank account

bankAddress
string

Bank address

bankCountry
string

Bank country

routingCodeList
Array

List of routing codes

Example:
[
    {
        "key": "sort_code",
        "value": "123123"
    }
]
Object
key
string
Enumeration:
aba
blz_code
branch_code
bsb_code
sort_code
ifs_code
clabe_code
ctn
value
string

Value of the routing code

Example request
Example response

Sample create a currency account request

curl -X "POST" "https://sandbox-api.openpayd.com/api/v1/currency-accounts" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "currency": "USD"
}'

Sample create a currency account response

{"currency":"USD",
"status":"active",
"balance":0,
"bankName":"SIM BANK",
"bankAccountHolderName":"SIM ACCOUNT",
"accountNumber":"12345678",
"bicSwift":"SIM0000",
"iban":"SM000000000000000000000000",
"bankAddress":null,
"bankCountry":null,
"routingCodeList":null}
List currency accounts
GET /currency-accounts

Returns the authenticated user’s currency accounts.

Request parameters

pageNumber
string required
Example:
1
pageSize
string required
Example:
100
currency
string optional

Three letter currency code

Example:
GBP
status
string optional
Enumeration:
active
inactive
minBalance
string optional

Minimum balance

maxBalance
string optional

Maximum balance

onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

scope
string optional

Listing scope

Enumeration:
all

list everything (owned by main client and linked clients)

main

owned by main client

linked

owned by the linked client specified on “onBehalfOf” parameter

Default:
all

Responses

200 OK

Successful response will contain an array of the following response body

Body
Object
currency
string

Three letter currency code

status
string

active or inactive

balance
number

currency account balance

bankName
string

Bank name

bankAccountHolderName
string

Name of bank account holder

accountNumber
string

Bank account number

bicSwift
string

Bic or swift for the bank account

iban
string

Bank IBAN number

bankAddress
string

Bank address

bankCountry
string

Two digit bank country code

routingCodeList
Array

List of routing codes as key-value pairs

Examples:
routingCodeList
[
    {
        "key": "sort_code",
        "value": "123123"
    }
]
Object
key
string
value
string
clientId
string

Id of the client that owns the currency account

Example request
Example response

sample request to list currency accounts

curl -X GET \
  'https://sandbox-api.openpayd.com/api/v1/currency-accounts/?pageSize=100&pageNumber=1' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'

sample response to list currency accounts

"currencyAccountList": [
        {
            "currency": "GBP",
            "status": "active",
            "balance": 912,
            "clientId": "3a63c0a6-0254-42cb-8c1b-15c246a52026",
            "bankName": "SIM BANK",
            "bankAccountHolderName": "SIM ACCOUNT",
            "accountNumber": "12345678",
            "bicSwift": "SIM0000",
            "iban": "DE04700TESTIBAN0000084",
            "bankAddress": null,
            "bankCountry": null,
            "routingCodeList": null
        },
        {
            "currency": "USD",
            "status": "active",
            "balance": 100,
            "clientId": "3a63c0a6-0254-42cb-8c1b-15c246a52026",
            "bankName": null,
            "bankAccountHolderName": null,
            "accountNumber": null,
            "bicSwift": null,
            "iban": null,
            "bankAddress": null,
            "bankCountry": null,
            "routingCodeList": null
        },
        {
            "currency": "EUR",
            "status": "active",
            "balance": 190,
            "clientId": "3a63c0a6-0254-42cb-8c1b-15c246a52026",
            "bankName": "SIM BANK",
            "bankAccountHolderName": "SIM ACCOUNT",
            "accountNumber": "12345678",
            "bicSwift": "SIM0000",
            "iban": "DE04700TESTIBAN0000090",
            "bankAddress": null,
            "bankCountry": null,
            "routingCodeList": null
        },
        {
            "currency": "TRY",
            "status": "active",
            "balance": 0,
            "clientId": "3a63c0a6-0254-42cb-8c1b-15c246a52026",
            "bankName": null,
            "bankAccountHolderName": null,
            "accountNumber": null,
            "bicSwift": null,
            "iban": null,
            "bankAddress": null,
            "bankCountry": null,
            "routingCodeList": null
        }}]}
Get currency account
GET /currency-accounts/{currency}

Retrieves the currency account by specified currency code.

Path variables

currency
string required

Three letter currency code

Example:
GBP

Request parameters

onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

Responses

200 OK
Body
Object
currency
string

Three letter currency code

status
string
Enumeration:
active
inactive
balance
number

Currency account balance

bankName
string

Bank name

bankAccountHolderName
string

Bank account holder name

accountNumber
string

Bank account number

bicSwift
string

Bic or swift for the bank account

iban
string

Bank account IBAN number

bankAddress
string

Bank address

bankCountry
string

Two digit bank country code

routingCodeList
Array

List of routing codes

Example:
[
    {
        "key": "sort_code",
        "value": "123123"
    }
]
Object
key
string
value
string
Example request
Example response

sample request to retrieve a currency account

curl "https://sandbox-api.openpayd.com/api/v1/currency-accounts/GBP" \
          -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2VjQGNvZGVzcGFjZWRldi5jb20iLCJpbnN0YW5jZUlkIjoiMSIsInJvbGUiOlsiVVNSIl0sImNoYW5uZWwiOiJBUEkiLCJzZXNzaW9uSWQiOiI0ZmRmZjc3OS02ZDE1LTQ2ZmEtOTJjMi0yYTEyNzVmMDhmNmIiLCJsb2dpbkV2ZW50SWQiOiI4NzQiLCJ0eXBlIjoiMSIsImV4cCI6MTUyMTAxNTc4NiwidXNlcklkIjoiMTE3IiwiaWF0IjoxNTIxMDEyMTg2fQ.rBZIy5okAp5wiToXtEXAczHwHy2Mr-ACGANp4jF1eR_CW8lQ2xOGxwouq0AtvrsqQATpYSciKvNH51SbLoettA'

sample response to retrieve a currency account

{"currency":"GBP",
 "status":"active",
 "balance":0.00,
 "bankName":"SIM BANK",
 "bankAccountHolderName":"SIM ACCOUNT",
 "accountNumber":"12345678",
 "bicSwift":"SIM0000",
 "iban":"DE04700TESTIBAN0000084",
 "bankAddress":null,
 "bankCountry":null,
 "routingCodeList":null}
List Balance Histories
GET /currency-accounts/balance-history

Returns the balance history of OpenPayd user’s currency accounts. A date range can be specified to retrieve balances during a specific time period.

Request parameters

pageNumber
string required
Example:
1
pageSize
string required
Example:
100
currency
string optional

Three letter currency code

minDate
string optional

Starting date to filter results

Example:
2017-01-01
maxDate
string optional

End date to filter results

Example:
2018-01-01
onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

Responses

200 OK

Successful response will be an array of below response object.

Body
Object
currency
string

Three letter currency code

date
string

Date of balance change

openingBalance
string

Balance before change

closingBalance
string

Balance after change

Example request
Example response

sample request to list balance histories

curl "https://sandbox-api.openpayd.com/api/v1/currency-accounts/balance-history?pageSize=100&pageNumber=1&minDate=2017-01-01&maxDate=2018-03-18" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{}'

sample response to list balance histories

{"pagination":{"totalEntryCount":2,"totalPageCount":1,"currentPage":1,
 "maximumPageSize":100,"currentPageSize":2,"previousPage":0,"nextPage":0},
 "balanceList":[
 {"currency":"GBP",
  "date":"2018-03-16",
  "openingBalance":0.00,
  "closingBalance":100.00},
  {"currency":"USD",
  "date":"2018-03-16",
  "openingBalance":0.00,
  "closingBalance":100.00}]}
Get pay-in
GET /pay-ins/{id}

Returns the pay-in (deposit into currency account) specified by the pay-in id.

Path variables

id
string required

Pay-in id

Request parameters

onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

Responses

200 OK
Body
Object
id
string

Pay-in id

amount
number

Transaction amount

currency
string

Three letter currency code

transactionReference
string

OpenPayd system reference number in human readable format

transactionDateTime
string

Time and date of transaction

senderName
string

Sender name

senderAddress
string

Sender address

senderBic
string

Sender bank indetifier code

senderIban
string

Sender iban

senderInformation
string

Sender information

Example request
Example response

sample request to get pay-in

   curl "https://sandbox-api.openpayd.com/api/v1/pay-ins/8be9c226-44d5-4155-8c3c-8ba5acc8dc4f" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'

sample response to get pay-in

   "id":"8be9c226-44d5-4155-8c3c-8ba5acc8dc4f",
   "amount":50.00,
   "currency":"GBP",
   "transactionReference":"20180320-1E1QK9",
   "transactionDateTime":"2018-03-20T07:57:52",
   "senderName":null,
   "senderAddress":null,
   "senderBic":null,
   "senderIban":null,
   "senderInformation":null
List pay-in
GET /pay-ins

Lists payments received on user’s currency accounts.

Request parameters

pageNumber
string required
Example:
1
pageSize
string required
Example:
100
onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

currency
string optional

Filter results by three letter currency code

minTransactionAmount
string optional

Filter by minimum transaction amount

maxTransactionAmount
string optional

Filter by maximum transaction amount

minTransactionDate
string optional

Filter by minimum transaction date

Example:
2017-01-01
maxTransactionDate
string optional

Filter by maximum transaction date

Example:
2018-01-01
scope
string optional

Listing scope

Enumeration:
all

list everything (owned by main client and linked clients)

main

owned by the main client

linked

owned by the linked client specified on “onBehalfOf” parameter

Default:
all

Responses

200 OK

Successful response will return an array of below response object.

Body
Object
id
string

Pay-in id

amount
number

Transaction amount

currency
string

Three letter currency code

transactionReference
string

OpenPayd system reference number in human readable format

transactionDateTime
string

Time and date of transaction

senderName
string

Sender name

senderAddress
string

Sender address

senderBic
string

Sender bank identifier code

senderIban
string

Sender iban

senderInformation
string

sender information

clientId
string

Id of the client that received the payment

Example request
Example response

sample request to list pay-ins

  curl "https://sandbox-api.openpayd.com/api/v1/pay-ins?pageSize=100&pageNumber=1" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'

sample response to list pay-ins

  "pagination":{"totalEntryCount":1,"totalPageCount":1,"currentPage":1,"maximumPageSize":100,
  "currentPageSize":1,"previousPage":0,"nextPage":0},"transactionList":[
  {"id":"8be9c226-44d5-4155-8c3c-8ba5acc8dc4f",
   "amount":50.00,
   "currency":"GBP",
   "clientId":"3a63c0a6-0254-42cb-8c1b-15c246a52026"
   "transactionReference":"20180320-1E1QK9",
   "transactionDateTime":"2018-03-20T07:57:52",
   "senderName":null,
   "senderAddress":null,
   "senderBic":null,
   "senderIban":null,
   "senderInformation":null}]} 
Payment

POST /payments
POST /payments/validate
GET /payments
GET /payments/{id}
GET /payments/external/{id}
POST /payments/{id}/cancel
POST /payments/external/{id}/cancel
Create payment
POST /payments

Creates a payment from a currency account to a beneficiary account.

Request body

Object
currency
string required

Three letter currency code. Currency account must be active and supported.

amount
number required

Payment amount

paymentDate
string required

Payment date

Example:
2017-12-31
paymentType
string required
Enumeration:
standard
express
faster_payments
chaps
sepa
reasonCode
string required
Enumeration:
personal
goods
staff
overheads
funds
income
other
reason
string required

If reasonCode is other then a text reason explanation is required

beneficiaryId
string required

Receiver beneficiary account id

paymentReference
string required

End-to-end reference entered by the payer which will be received by the payee on the other end. It can be used for reconciliation purposes.

externalId
string

Client generated unique reference number

onBehalfOf
string

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

feeQuoteReference
string

Fee quote reference

Responses

200 OK
Body

The following fields are only populated if the currency account’s balance is insufficient and a pay in (deposit) is required to complete the payment. The payin fields are specifying the bank account that requires the deposit.

Fields
payInBankName
payInBankAccountHolderName
payInAccountNumber
payInBicSwift
payInIban
payInReference
Object
id
string

Payment id

currency
string

Payment currency

amount
number

Payment amount

paymentDate
string

Payment date

beneficiaryId
string

Beneficiary id that received the payment

paymentType
string
Enumeration:
standard
express
faster_payments
chaps
sepa
reason
string

Reason for payment

reasonCode
string
Enumeration:
personal
goods
staff
overheads
funds
income
other
paymentReference
string

End-to-end reference entered by the payer which will be received by the payee on the other end. It can be used for reconciliation purposes.

paymentStatus
string

Payment status

Enumeration:
waiting_client_confirmation
pending
processing
released
completed
canceled
failed
externalId
string

Client generated unique reference number

payInBankName
string

Name of bank that expects the pay-in

payInBankAccountHolderName
string

Bank account holder name for the pay-in

payInAccountNumber
string

Bank account that expects the pay-in

payInBicSwift
string

Bic/Swift number for the pay-in account

payInIban
string

Iban for the pay-in account

payInReference
string

Pay-in reference number

onBehalfOf
string

If a main client is creating this payment transaction on behalf of a linked client, id of the linked client performing the payment is specified on this parameter

transactionReference
string

OpenPayd system reference number in human readable format

creationDateTime
string

Date and time of request

clientId
string

Id of the client that performed the conversion

Example request
Example response

sample request to create a payment

curl -X "POST" "https://sandbox-api.openpayd.com/api/v1/payments" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
   "currency": "GBP",
   "amount": 358870,
   "paymentDate": "2019-07-26",
   "beneficiaryId": "f26aa97f-bee5-47c2-bf46-2daacf55fafb",
   "paymentType": "standard",
   "reason":"lorem ipsum",
   "reasonCode":"other",
   "paymentReference":"REFERENCE-A000BC",
   "feeQuoteReference": "91ca2c30-462f-4419-98b5-023e9f135da3"
}

sample response to create a payment

{
    "id": "2e36f60f-2ee7-413f-9cd1-bf2f59de9035",
    "clientId": "f5a4a5d2-05d1-4759-96c5-1f9ca792c7f7",
    "externalId": null,
    "currency": "GBP",
    "amount": 35910,
    "paymentDate": "2019-07-26",
    "beneficiaryId": "f26aa97f-bee5-47c2-bf46-2daacf55fafb",
    "paymentType": "standard",
    "reasonCode": "other",
    "reason": "lorem ipsum",
    "paymentReference": "REFERENCE-A000BC",
    "paymentStatus": "pending",
    "transactionReference": "20190704-VOLRXV",
    "totalFees": 98.72,
    "totalDebitAmount": 36008.72,
    "hasEnoughBalance": false,
    "feeCollectionType": "onsource",
    "creationDateTime": "2019-07-04T10:19:48.953",
    "payInBankName": "Clear Bank",
    "payInBankAccountHolderName": "eror",
    "payInAccountNumber": "00000017",
    "payInBicSwift": "CLRBGB22",
    "payInIban": "GB35CLRB04050900000017",
    "payInReference": null
}
Validate payment
POST /payments/validate

Validates a payment without creating a payment request. This endpoint uses the same request and response structure as create payment endpoint.

Request body

Object
currency
string required

Three letter currency code. Currency account must be active and supported.

Example:
GBP
amount
number required

Payment amount

Example:
300
paymentDate
string required
Example:
2017-12-31
beneficiaryId
string required

Receiver beneficiary account id

paymentType
string
Enumeration:
express
standard
faster_payments
chaps
sepa
reasonCode
string required
Enumeration:
personal
goods
staff
overheads
funds
income
other
reason
string required

If reasonCode is other then a text reason explanation is required

paymentReference
string required

End-to-end reference entered by the payer which will be received by the payee on the other end. It can be used for reconciliation purposes.

onBehalfOf
string

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

Responses

200 OK
Body
Object
currency
string

Payment id

amount
string

Payment currency

paymentDate
string

Payment date

beneficiaryId
string

Beneficiary id that received the payment

paymentType
string
Enumeration:
standard
express
faster_payments
chaps
sepa
reasonCode
string
Enumeration:
personal
goods
staff
overheads
funds
income
other
reason
string

Reason for payment

paymentReference
string

End-to-end reference entered by the payer which will be received by the payee on the other end. It can be used for reconciliation purposes.

feeQuoteReference
string

Fee quote for payment creation

totalFees
string

Payment fee amount

totalDebitAmount
string

Payment amount + fee amount

hasEnoughBalance
string

Is balance enough flag

feeCollectionType
string
Enumeration:
invoice
onsource
parent_invoice
parent_onsource
Example Request
Example Response
 curl -X "POST" "https://sandbox-api.openpayd.com/api/v1/payments/validate" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
   "currency": "GBP",
   "amount": 400.00,
   "paymentDate": "2019-07-26",
   "beneficiaryId": "f26aa97f-bee5-47c2-bf46-2daacf55fafb",
   "paymentType": "standard",
   "reason":"lorem ipsum",
   "reasonCode":"other",
   "paymentReference":"REFERENCE-A001BC"
}
{
    "currency": "GBP",
    "amount": 400,
    "paymentDate": "2019-07-26",
    "beneficiaryId": "f26aa97f-bee5-47c2-bf46-2daacf55fafb",
    "paymentType": "standard",
    "reasonCode": "other",
    "reason": "lorem ipsum",
    "paymentReference": "REFERENCE-A001BC",
    "feeQuoteReference": "d036ee7f-36c7-4e0b-9ee6-2e187aa35ee8",
    "totalFees": 98.73,
    "totalDebitAmount": 498.73,
    "hasEnoughBalance": true,
    "feeCollectionType": "onsource",
    "payInBankName": null,
    "payInBankAccountHolderName": null,
    "payInAccountNumber": null,
    "payInBicSwift": null,
    "payInIban": null,
    "payInReference": null
}
List payments
GET /payments

Lists payments for the authenticated OpenPayd user.

Request parameters

Request uses the following URL parameters.

pageNumber
string required
Example:
1
pageSize
string required
Example:
100
scope
string optional

Listing scope

Enumeration:
all

list everything (owned by main client and linked clients)

main

owned by main client

linked

owned by the linked client specified on “onBehalfOf” parameter

Default:
all

Request body

Following request parameters are optional.

Object
minCreationDate
string

Filter results by creation date from requested date onwards

Example:
2017-01-01
maxCreationDate
string

Filter results by creation date until requested date

Example:
2017-12-01
minPaymentDate
string

Filter results by payment date from requested date onwards

Example:
2017-01-01
maxPaymentDate
string

Filter results by payment date until requested date

Example:
2017-12-01
reference
string

Filter results by payment reference

currency
string

Filter by three digit currency code

minAmount
number

Filter results by minimum payment amount

Example:
10
maxAmount
number

Filter results by maximum payment amount

beneficiaryId
string

Filter by beneficiary id

paymentStatus
string
Enumeration:
waiting_client_confirmation
pending
processing
released
completed
canceled
failed
onBehalfOf
string

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

Responses

200 OK

Successful response returns an array of the below response object.

Body
Object
id
string

Payment id

currency
string

Three letter currency code

amount
number

Payment amount

paymentDate
string

Date of payment

beneficiaryId
string

Beneficiary id that received the payment

paymentType
string
Enumeration:
standard
express
faster_payments
chaps
sepa
reasonCode
string
Enumeration:
personal
goods
staff
overheads
funds
income
other
reason
string

Payment reason

paymentReference
string

End-to-end reference entered by the payer which will be received by the payee on the other end. It can be used for reconciliation purposes.

paymentStatus
string

Payment status

Enumeration:
waiting_client_confirmation
pending
processing
released
completed
canceled
failed
externalId
string

Client generated unique reference number

transactionReference
string

OpenPayd system reference number in human readable format

clientId
string

Id of the client that performed the payment

creationDateTime
string

Time and date when payment created

completionDateTime
string

Time and date when payment completed

Example request
Example response

sample request to list payments

curl "https://sandbox-api.openpayd.com/api/v1/payments?pageSize=100&pageNumber=1" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'

sample response to list payments

{"pagination":{"totalEntryCount":1,"totalPageCount":1,"currentPage":1,
 "maximumPageSize":100,"currentPageSize":1,"previousPage":0,"nextPage":0},
 "paymentList":[
 {"id": "db08557a-3e97-42b4-994d-b0d2a5a8ceaa",
   "externalId": "testBankPayment132",
   "clientId": "3a63c0a6-0254-42cb-8c1b-15c246a52026",
   "currency": "GBP",
   "amount": 1189,
   "paymentDate": "2018-03-21",
   "beneficiaryId": "e45d0182-a473-4dd7-892b-07692a522f91",
   "paymentType": "standard",
   "reasonCode": "other",
   "reason": "other",
   "paymentReference": "13378",
   "paymentStatus": "pending",
   "transactionReference": "20180509-G9RDJE",
   "creationDateTime":"2018-03-16T13:06:24.319",
   "completionDateTime":"2018-03-16T13:30:45.230"
 }]}
Get payment by id
GET /payments/{id}

Retrieves a payment by payment id.

Path variables

id
string required

Payment id

Request parameters

onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

Responses

200 OK
Body
Object
id
string

Payment id

currency
string

Three letter currency code

amount
number

Payment amount

paymentDate
string

Date of payment

beneficiaryId
string

Beneficiary id that received the payment

paymentType
string
Enumeration:
standard
express
faster_payments
chaps
sepa
reasonCode
string
Enumeration:
personal
goods
staff
overheads
funds
income
other
reason
string

Payment reason

paymentReference
string

End-to-end reference entered by the payer which will be received by the payee on the other end. It can be used for reconciliation purposes.

paymentStatus
string

Payment status

Enumeration:
waiting_client_confirmation
pending
processing
released
completed
canceled
failed
externalId
string

Client generated unique reference number

transactionReference
string

OpenPayd system reference number in human readable format

beneficiaryExternalId
string

Client generated unique reference number

beneficiaryName
string

Beneficiary name

beneficiaryType
string

retail or corporate

beneficiaryFirstName
string

Only required if type is retail

beneficiaryLastName
string

Only required if type is retail

beneficiaryBirthDate
string

Only required if type is retail

beneficiaryCompanyName
string

Only required if type is corporate, title of company

beneficiaryCountry
string

Beneficiary address country

beneficiaryState
string

Beneficiary address state

beneficiaryPostalCode
string

Beneficiary address postal code

beneficiaryCity
string

Beneficiary address city

beneficiaryAddressLine
string

Beneficiary address line

beneficiaryAccountNumber
string

Beneficiary account number

beneficiaryIban
string

Beneficiary account iban

beneficiaryBic
string

Beneficiary account bank identifier code

beneficiaryCurrency
string

Three letter currency code

beneficiaryBankAccountCountry
string

Beneficiary bank account country

Example:
GB
beneficiaryBankAccountHolderName
string

Beneficiary bank account holder name

beneficiaryPaymentTypeList
Array of string

one or two of standard, express, faster_payments, chaps, sepa

Example:
[
        "standard"
    ]
beneficiaryRoutingCodeList
Array
Example:
[
   {
        "key": "sort_code",
        "value": "123123"
    }
]
Object
key
string
value
string
beneficiaryBankName
string

Beneficiary bank name

beneficiaryBankAddress
string

Beneficiary bank address

totalFees
number

Total fee

creationDateTime
string

Time and date when conversion created

completionDateTime
string

Time and date when conversion completed

Example request
Example response

sample request to get a payment by id

 curl "https://sandbox-api.openpayd.com/api/v1/payments/d74df780-71d7-4b73-8f00-2750c2ab80ee" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2'

sample response to get a payment by id

{
    "id": "9265fbd2-b66f-4d5f-a0f7-71088a8cab9e",
    "externalId": null,
    "currency": "GBP",
    "amount": 35910,
    "paymentDate": "2019-07-26",
    "paymentType": "standard",
    "reasonCode": "other",
    "reason": "lorem ipsum",
    "paymentReference": "REFERENCE-A000BC",
    "paymentStatus": "completed",
    "transactionReference": "20190704-EPLZ19",
    "beneficiaryId": "f26aa97f-bee5-47c2-bf46-2daacf55fafb",
    "beneficiaryExternalId": "12345678-1234-5678-1234-567812349678",
    "beneficiaryName": "Mysterious Beneficiary",
    "beneficiaryType": "corporate",
    "beneficiaryFirstName": null,
    "beneficiaryLastName": null,
    "beneficiaryBirthDate": null,
    "beneficiaryCompanyName": "Murder Mistery Business",
    "beneficiaryCountry": "GB",
    "beneficiaryState": null,
    "beneficiaryPostalCode": "12345",
    "beneficiaryCity": "London",
    "beneficiaryAddressLine": "221B Baker Street",
    "beneficiaryAccountNumber": "12332143",
    "beneficiaryIban": "GB85CLRB04050900000281",
    "beneficiaryBic": "BUKBGB22",
    "beneficiaryCurrency": "GBP",
    "beneficiaryBankAccountCountry": "GB",
    "beneficiaryBankAccountHolderName": "Sherlock Holmes",
    "beneficiaryPaymentTypeList": [
        "standard"
    ],
    "beneficiaryRoutingCodeList": [
        {
            "key": "sort_code",
            "value": "123123"
        }
    ],
    "beneficiaryBankName": null,
    "beneficiaryBankAddress": null,
    "totalFees": 98.73,
    "creationDateTime": "2019-07-04T10:20:48.495",
    "completionDateTime": "2019-07-04T10:25:15.210",
}
Get payment by external id
GET /payments/external/{id}

Retrieves a payment by an external id.

Path variables

id
string required

External id (specified on payment creation)

Request parameters

onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

Responses

200 OK
Body
Object
id
string

Payment id

currency
string

Three letter currency code

amount
number

Payment amount

paymentDate
string

Date of payment

beneficiaryId
string

Receiver beneficiary id

paymentType
string
Enumeration:
standard
express
faster_payments
chaps
sepa
reasonCode
string
Enumeration:
personal
goods
staff
overheads
funds
income
other
reason
string

Payment reason

paymentReference
string

End-to-end reference entered by the payer which will be received by the payee on the other end. It can be used for reconciliation purposes.

paymentStatus
string

Payment status

Enumeration:
waiting_client_confirmation
pending
processing
released
completed
canceled
failed
externalId
string

Client generated unique reference number

transactionReference
string

OpenPayd system reference number in human readable format

beneficiaryExternalId
string

Client generated unique reference number

beneficiaryName
string

Beneficiary name

beneficiaryType
string

retail or corporate

beneficiaryFirstName
string

Only required if type is retail

beneficiaryLastName
string

Only required if type is retail

beneficiaryBirthDate
string

Only required if type is retail

beneficiaryCompanyName
string

Only required if type is corporate, title of company

beneficiaryCountry
string

Beneficiary address country

beneficiaryState
string

Beneficiary address state

beneficiaryPostalCode
string

Beneficiary address postal code

beneficiaryCity
string

Beneficiary address city

beneficiaryAddressLine
string

Beneficiary address line

beneficiaryAccountNumber
string

Beneficiary account number

beneficiaryIban
string

Beneficiary account iban

beneficiaryBic
string

Beneficiary account bank identifier code

beneficiaryCurrency
string

Three letter currency code

beneficiaryBankAccountCountry
string

Beneficiary bank account country

beneficiaryBankAccountHolderName
string

Beneficiary bank account holder name

beneficiaryPaymentTypeList
Array of string

one or two of standard, express, faster_payments, chaps, sepa

Example:
[
    "standard"
]
beneficiaryRoutingCodeList
Array
Example:
[
   {
        "key": "sort_code",
        "value": "123123"
    }
]
Object
key
string
value
string
beneficiaryBankName
string

Beneficiary bank name

beneficiaryBankAddress
string

Beneficiary bank address

totalFees
string

Total fee

creationDateTime
string

Time and date when conversion created

completionDateTime
string

Time and date when conversion completed

Example response

sample response to get payment by external id

{
    "id": "9265fbd2-b66f-4d5f-a0f7-71088a8cab9e",
    "externalId": "12345678-1234-5678-1234-567812345678",
    "currency": "GBP",
    "amount": 35910,
    "paymentDate": "2019-07-26",
    "paymentType": "standard",
    "reasonCode": "other",
    "reason": "lorem ipsum",
    "paymentReference": "REFERENCE-A000BC",
    "paymentStatus": "completed",
    "transactionReference": "20190704-EPLZ19",
    "beneficiaryId": "f26aa97f-bee5-47c2-bf46-2daacf55fafb",
    "beneficiaryExternalId": "12345678-1234-5678-1234-567812349678",
    "beneficiaryName": "Mysterious Beneficiary",
    "beneficiaryType": "corporate",
    "beneficiaryFirstName": null,
    "beneficiaryLastName": null,
    "beneficiaryBirthDate": null,
    "beneficiaryCompanyName": "Murder Mistery Business",
    "beneficiaryCountry": "GB",
    "beneficiaryState": null,
    "beneficiaryPostalCode": "12345",
    "beneficiaryCity": "London",
    "beneficiaryAddressLine": "221B Baker Street",
    "beneficiaryAccountNumber": "12332143",
    "beneficiaryIban": "GB85CLRB04050900000281",
    "beneficiaryBic": "BUKBGB22",
    "beneficiaryCurrency": "GBP",
    "beneficiaryBankAccountCountry": "GB",
    "beneficiaryBankAccountHolderName": "Sherlock Holmes",
    "beneficiaryPaymentTypeList": [
        "standard"
    ],
    "beneficiaryRoutingCodeList": [
        {
            "key": "sort_code",
            "value": "123123"
        }
    ],
    "beneficiaryBankName": null,
    "beneficiaryBankAddress": null,
    "totalFees": 98.73,
    "creationDateTime": "2019-07-04T10:20:48.495",
    "completionDateTime": "2019-07-04T10:25:15.210",
}
Cancel payment by id
POST /payments/{id}/cancel

Cancels a payment request using the payment id.

Path variables

id
string required

Id of the payment that will be cancelled

Request parameters

onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

Responses

200 OK
Example request

sample request to cancel payment by id

 curl -X "POST" "https://sandbox-api.openpayd.com/api/v1/payments/d74df780-71d7-4b73-8f00-2750c2ab80ee/cancel" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'
Cancel payment by external id
POST /payments/external/{id}/cancel

Cancels the payment using the external id.

Path variables

id
string required

External id of the payment that will be cancelled. In the below curl example “testBankExt12” is used for external id.

Request parameters

onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

Responses

200 OK
Example request

sample request to cancel request by external id

curl -X "POST" "https://sandbox-api.openpayd.com/api/v1/payments/external/testBankExt12/cancel" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'
Beneficiary

A beneficiary account is a bank account you use to transfer funds from your currency accounts.

POST /beneficiaries
POST /beneficiaries/validate
GET /beneficiaries
GET /beneficiaries/{id}
GET /beneficiaries/external/{id}
POST /beneficiaries/{id}
DELETE /beneficiaries/{id}
DELETE /beneficiaries/external/{id}
Create a beneficiary
POST /beneficiaries

Creates a new beneficiary account.

Information that is required for creating a beneficiary bank account depends on various variables. Country specific fields such as sort code for UK, routing number for US, BLZ for Germany are few examples of bank account variations. If you are not sure of your beneficiary bank details, refer to Beneficiary required details endpoint to properly format your ‘create a beneficiary’ request.

Request body

If beneficiaryType is retail, firstName and lastName are required. If beneficiaryType is corporate, title is required.

Object
name
string required

Beneficiary name

beneficiaryType
string required

Corporate or retail

beneficiaryFirstName
string

Required for retail

beneficiaryLastName
string

Required for retail

companyName
string

Required for corporate

beneficiaryCountry
string required

Two letter country code

Example:
GB
beneficiaryPostalCode
string required

Postal code

beneficiaryCity
string required

City

beneficiaryAddressLine
string required

Address line

accountNumber
string

8 digit bank account number

iban
string

Iban

Example:
GB85CLRB04050900000281
bic
string

Bank identifier code

Example:
BUKBGB22
currency
string required

Three letter bank currency code

Example:
GBP
bankAccountCountry
string required

Two letter bank country code

Example:
GB
bankAccountHolderName
string required

Bank account holder name

paymentTypeList
string required
Enumeration:
express
standard
faster_payments
chaps
sepa
routingCodeList
Array

Routing code list as key-value pairs

Example:
[
    {
        "key": "sort_code",
        "value": "123123"
    }
]
Object
key
string
Enumeration:
aba
blz_code
branch_code
bsb_code
sort_code
ifs_code
clabe_code
ctn
value
string

Value of the routing code

bankName
string

Bank name

bankAddress
string

Bank address

onBehalfOf
string

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

externalId
string required

Client generatred unique reference number

beneficiaryState
string

State of country

Example:
WA
beneficiaryBirthDate
string

For retail beneficiary

Example:
2019-07-26

Responses

200 OK
Body
Object
id
string

Beneficiary id

externalId
string

Client generated unique reference number

name
string

Client specified beneficiary name or alias

beneficiaryType
string

Beneficiary type

beneficiaryFirstName
string

First name

beneficiaryLastName
string

Last name

companyName
string

Company name or title

beneficiaryCountry
string

Country

beneficiaryPostalCode
string

Postal code

beneficiaryState
string

State or province

beneficiaryCity
string

City

beneficiaryAddressLine
string

Address Line

AccountNumber
string

Account number

Iban
string

Account iban

Bic
string

Bank identifier code

Currency
string

Three letter currency code

bankAccountCountry
string

Bank country

bankAccountHolderName
string

Holder name on bank account

PaymentTypeList
string

Supported payment types

RoutingCodeList
Array

Routing code list

Example:
[
    {
        "key": "sort_code",
        "value": "123123"
    }
]
Object
key
string
value
string
BankName
string

Bank name

BankAddress
string

Bank address

onBehalfOf
string

If a main client is creating this beneficiary on behalf of a linked client, id of the linked client creating the beneficiary is specified on this parameter

Example request
Example response

sample request to create a benecificary

   curl -X "POST" "https://sandbox-api.openpayd.com/api/v1/beneficiaries" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
    "name": "Mysterious Beneficiary",
    "beneficiaryType": "corporate",
    "beneficiaryFirstName": null,
    "beneficiaryLastName": null,
    "beneficiaryBirthDate": null,
    "companyName": "Murder Mistery Business",
    "beneficiaryCountry": "GB",
    "beneficiaryState": null,
    "beneficiaryPostalCode": "12345",
    "beneficiaryCity": "London",
    "beneficiaryAddressLine": "221B Baker Street",
    "accountNumber": "12332143",
    "iban": "GB85CLRB04050900000281",
    "bic": "BUKBGB22",
    "currency": "GBP",
    "bankAccountCountry": "GB",
    "bankAccountHolderName": "Sherlock Holmes",
    "paymentTypeList": [
      "standard"
    ],
    "routingCodeList": [
      {
        "key": "sort_code",
        "value": "123123"
      }
    ],
    "bankName": "ABCD BANK",
    "bankAddress": "12345 Main Street",
    "externalId": "12345678-1234-5678-1234-567812345678"
}'

sample response to create a beneficiary

{
    "id": "506dfc7e-93bb-479f-98ca-9e64ebeaa330",
    "externalId": "12345678-1234-5678-1234-567812345678",
    "name": "Mysterious Beneficiary",
    "beneficiaryType": "corporate",
    "beneficiaryFirstName": null,
    "beneficiaryLastName": null,
    "beneficiaryBirthDate": null,
    "companyName": "Murder Mistery Business",
    "beneficiaryCountry": "GB",
    "beneficiaryState": null,
    "beneficiaryPostalCode": "12345",
    "beneficiaryCity": "London",
    "beneficiaryAddressLine": "221B Baker Street",
    "accountNumber": "12332143",
    "iban": "GB85CLRB04050900000281",
    "bic": "BUKBGB22",
    "currency": "GBP",
    "bankAccountCountry": "GB",
    "bankAccountHolderName": "Sherlock Holmes",
    "paymentTypeList": [
        "standard"
    ],
    "routingCodeList": [
        {
            "key": "sort_code",
            "value": "123123"
        }
    ],
    "bankName": "ABCD BANK",
    "bankAddress": "12345 Main Street"
}
Validate beneficiary
POST /beneficiaries/validate

Validates a beneficiary without creating a beneficiary account.

Request body

If beneficiaryType is retail, firstName and lastName are required. If beneficiaryType is corporate, title is required.

Object
name
string required

Beneficiary name

beneficiaryType
string required

Corporate or retail

beneficiaryFirstName
string

Required for retail

beneficiaryLastName
string

Required for retail

beneficiaryBirthDate
string

For retail beneficiary

Example:
2019-07-26
companyName
string

Required for corporate

beneficiaryCountry
string required

Two letter country code

Example:
GB
beneficiaryState
string

State of country

Example:
WA
beneficiaryPostalCode
string required

Postal code

beneficiaryCity
string required

City

beneficiaryAddressLine
string

Address line

accountNumber
string

8 digit bank account number

iban
string

Iban

Example:
GB85CLRB04050900000281
bic
string

Bank identifier code

Example:
BUKBGB22
currency
string required

Three letter bank currency code

Example:
GBP
bankAccountCountry
string required

Two letter bank country code

Example:
GB
bankAccountHolderName
string required

Bank account holder name

paymentTypeList
string required
Enumeration:
express
standard
faster_payments
chaps
sepa
routingCodeList
Array

Routing code list as key-value pairs

Example:
[
    {
        "key": "sort_code",
        "value": "123123"
    }
]
Object
key
string
Enumeration:
aba
blz_code
branch_code
bsb_code
sort_code
ifs_code
clabe_code
ctn
value
string

Value of the routing code

bankName
string

Bank name

bankAddress
string

Bank address

Responses

200 OK
Body
Object
bankName
string

Bank name

bankAccountType
string

Bank Account Type

bankAddress
string

Bank Address

Example request
Example response

sample request to validate a beneficiary

 curl -X "POST" "https://sandbox-api.openpayd.com/api/v1/beneficiaries/validate" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
    "name": "Mysterious Beneficiary",
    "beneficiaryType": "corporate",
    "beneficiaryFirstName": null,
    "beneficiaryLastName": null,
    "beneficiaryBirthDate": null,
    "companyName": "Murder Mistery Business",
    "beneficiaryCountry": "GB",
    "beneficiaryState": null,
    "beneficiaryPostalCode": "12345",
    "beneficiaryCity": "London",
    "beneficiaryAddressLine": "221B Baker Street",
    "accountNumber": "12332143",
    "iban": "GB85CLRB04050900000281",
    "bic": "BUKBGB22",
    "currency": "GBP",
    "bankAccountCountry": "GB",
    "bankAccountHolderName": "Sherlock Holmes",
    "paymentTypeList": [
      "standard"
    ],
    "routingCodeList": [
      {
        "key": "sort_code",
        "value": "123123"
      }
    ],
    "bankName": "ABCD BANK",
    "bankAddress": "12345 Main Street",
}'

sample response to validate a beneficiary

{
    "bankName": "ABCD BANK",
    "bankAccountType": null,
    "bankAddress": "TEST ADDRESS"
}
List beneficiaries
GET /beneficiaries

Lists beneficiary accounts for the authenticated OpenPayd user.

Request parameters

pageNumber
string required
Example:
1
pageSize
string required
Enumeration:
100
scope
string optional

Listing scope

Enumeration:
all

list everything (owned by main client and linked clients)

main

owned by main client

linked

owned by the linked client specified on “onBehalfOf” parameter

Default:
all

Request body

Following parameters are optional.

Object
beneficiaryName
string

Filter by beneficiary name

currency
string

Filter by three letter currency code

bankCountry
string

Filter by two letter country code

Example:
GB
paymentType
string
Enumeration:
standard
express
faster_payments
chaps
sepa
externalId
string

Client generated unique reference number

onBehalfOf
string

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

Responses

200 OK

Successful response will return an array of the below response object.

Body
Object
id
string

Beneficiary id

externalId
string

Client generated unique reference number

beneficiaryName
string

Name of beneficiary

bankCountryName
string

Beneficiary bank country name

currency
string

Three letter currency code

clientId
string

Id of the client that is associated with the beneficiary account

Example request
Example response

sample request to list beneficiaries

curl "https://sandbox-api.openpayd.com/api/v1/beneficiaries?pageSize=100&pageNumber=1" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{}'

sample response to list beneficiaries

{"pagination":{"totalEntryCount":1,"totalPageCount":1,"currentPage":1,
 "maximumPageSize":100,"currentPageSize":1,"previousPage":0,"nextPage":0},
 "beneficiaryList":[
 {"id":"e45d0182-a473-4dd7-892b-07692a522f91",
  "externalId":null,
  "beneficiaryName":"First test bene",
  "currency":"GBP",
  "clientId": "3a63c0a6-0254-42cb-8c1b-15c246a52023",
  "bankCountryName":"United Kingdom of Great Britain and Northern Ireland"}]}
Get beneficiary by id
GET /beneficiaries/{id}

Returns the beneficiary account by beneficiary id.

Path variables

id
string required

Beneficiary id

Request parameters

onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

Responses

200 OK
Body
Object
id
string

Beneficiary id

name
string

Beneficiary name

currency
string

Three letter currency code

bankAccountCountry
string

Bank country code

externalId
string

Client generated unique reference number

beneficiaryType
string

retail or corporate

beneficiaryFirstName
string

Only required if type is retail

beneficiaryLastName
string

Only required if type is retail

companyName
string

Only required if type is corporate, title of company

beneficiaryCountry
string

Address country

beneficiaryState
string

State

beneficiaryPostalCode
string

Postal code

beneficiaryCity
string

City

beneficiaryAddressLine
string

Address line

accountNumber
string

Account number

iban
string

Account iban

bic
string

Account bank identifier code

bankAccountHolderName
string

Account holder name

paymentTypeList
Array of string

one or two of standard, express, faster_payments, chaps, sepa

Example:
[
        "standard"
    ]
routingCodeList
Array
Example:
[
    {
        "key": "sort_code",
        "value": "123123"
    }
]
Object
key
string
value
string
bankName
string

Bank name

bankAddress
string

Bank address

Example request
Example response

sample request to get beneficiary by id

curl "https://sandbox-api.openpayd.com/api/v1/beneficiaries/e45d0182-a473-4dd7-892b-07692a522f91" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'

sample response to get beneficiary by id

   {"id":"e45d0182-a473-4dd7-892b-07692a522f91",
    "externalId": "1115748-1234-4444-1234-567812345680",
    "name": "Sandbox Tester New Beneficiary 2",
    "beneficiaryType": "corporate",
    "beneficiaryFirstName": null,
    "beneficiaryLastName": null,
    "companyName": "Tester Business N1",
    "beneficiaryCountry": "GB",
    "beneficiaryState": null,
    "beneficiaryPostalCode": "12345",
    "beneficiaryCity": "London",
    "beneficiaryAddressLine": "221B Baker Street",
    "accountNumber": "12312312",
    "iban": null,
    "bic": null,
    "currency": "GBP",
    "bankAccountCountry": "GB",
    "bankAccountHolderName": "Sherlock Holmes",
    "paymentTypeList": [
        "standard"
    ],
    "routingCodeList": [
        {
            "key": "sort_code",
            "value": "123123"
        }
    ],
    "bankName": "TEST BANK",
    "bankAddress": "TEST ADDRESS"}
Get beneficiary by external id
GET /beneficiaries/external/{id}

Returns the beneficiary by the external id. This endpoint uses the same request and response structure as get beneficiary by id endpoint.

Path variables

id
string required

External id

Update beneficiary
POST /beneficiaries/{id}

Updates the beneficiary specified by the beneficiary id.

Path variables

id
string required

Beneficiary id

Request body

Fields that are not specified on the update request will be set to null.

Object
bankAddress
string

Bank line address

companyName
string

Company title

paymentTypeList
string
Enumeration:
express
standard
faster_payments
chaps
sepa
bankAccountHolderName
string

Account holder name

iban
string

Bank account iban

currency
string

Three letter account currency code

beneficiaryLastName
string

Last name

beneficiaryFirstName
string

First name

name
string

Client specified beneficiary name

bankAccountCountry
string

Two letter bank account country

Example:
GB
routingCodeList
Array

Routing codes as key-value pairs

Example:
[
    {
        "key": "sort_code",
        "value": "123123"
    }
]
Object
key
string
Enumeration:
aba
blz_code
bsb_code
branch_code
sort_code
ifs_code
clabe_code
ctn
value
string

Value of the routing code

beneficiaryType
string

Corporate or retail

bic
string

Bank identifier code

accountNumber
string

Bank account number

bankName
string

Bank name

externalId
string

Client generated unique reference number

onBehalfOf
string

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

beneficiaryBirthDate
string

Birth date

beneficiaryCountry
string

Two letter country code

Example:
GB
beneficiaryState
string

State of country

beneficiaryCity
string

City name

Example:
London
beneficiaryPostalCode
string

Beneficiary postal code

beneficiaryAddressLine
string

Address line

Responses

200 OK
Body
Object
id
string

Beneficiary id

externalId
string

Client generated unique reference number

name
string

Client specified beneficiary name

beneficiaryType
string

Corporate or retail

beneficiaryFirstName
string

First name

beneficiaryLastName
string

Last name

companyName
string

Company title

beneficiaryCountry
string

Two letter beneficiary country code

beneficiaryState
string

Beneficiary state or province code

beneficiaryPostalCode
string

Beneficiary postal code

beneficiaryCity
string

Beneficiary city

beneficiaryAddressLine
string

Beneficiary address line

accountNumber
string

Account number

iban
string

Iban

bic
string

Bank identifier code

currency
string

Three letter currency code

bankAccountCountry
string

Two letter country code of bank account country

bankAccountHolderName
string

Account holder name

paymentTypeList
string
Enumeration:
express
standard
faster_payments
chaps
sepa
routingCodeList
Array
Example:
[
    {
        "key": "sort_code",
        "value": "123123"
    }
]
Object
key
string
value
string
bankName
string

Bank name

bankAddress
string

Bank address

onBehalfOf
string

If a main client is updating this beneficiary on behalf of a linked client, id of the linked client updating the beneficiary is specified on this parameter

Example request
Example response

sample request to update beneficiary

curl -X "POST" "https://sandbox-api.openpayd.com/api/v1/beneficiaries/e45d0182-a473-4dd7-892b-07692a522f91" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "bankAddress": "12345 Main Street",
  "beneficaryFirstName": null,
  "paymentTypeList": [
    "standard"
  ],
  "bankAccountHolderName": "Sherlock Holmes",
  "iban": "GB11000010015555999966",
  "currency": "GBP",
  "beneficiaryLastName": null,
  "beneficiaryCountry": "GB",
  "beneficiaryCity": "London",
  "name": "Sandbox Tester Updated",
  "bankAccountCountry": "GB",
  "companyName": "Tester Business DEP",
  "routingCodeList": [
    {
      "key": "sort_code",
      "value": "123123"
    }
  ],
  "beneficiaryType": "corporate",
  "bic": "ABCDGB11",
  "accountNumber": "12312312",
  "bankName": "ABCD BANK",
  "beneficiaryAddressLine": "221B Baker Street",
  "externalId": "12365748-1234-4444-1234-567812345678",
  "beneficiaryPostalCode": "12345"
}'

sample response to update beneficiary

{"id":"e45d0182-a473-4dd7-892b-07692a522f91",
 "externalId":null,
 "name":"Sandbox Tester Updated",
 "beneficiaryType":"corporate",
 "beneficiaryFirstName":null,
 "beneficiaryLastName":null,
 "companyName":"Tester Business DEP",
 "beneficiaryCountry":"GB",
 "beneficiaryState":null,
 "beneficiaryPostalCode":"12345",
 "beneficiaryCity":"London",
 "beneficiaryAddressLine":"221B Baker Street",
 "accountNumber":"12312312",
 "iban":"GB11000010015555999966",
 "bic":"ABCDGB11",
 "currency":"GBP",
 "bankAccountCountry":"GB",
 "bankAccountHolderName":"Sherlock Holmes",
 "paymentTypeList": [
      "standard"
    ],
 "routingCodeList":[{"key":"sort_code","value":"123123"}],
 "bankName":"TEST BANK",
 "bankAddress":"TEST ADDRESS"}
Delete beneficiary by id
DELETE /beneficiaries/{id}

Deletes the beneficiary account specified by the beneficiary id.

Path variables

id
string required

Id of the beneficiary that will be deleted

Request parameters

onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

Example request

sample request to delete a beneficiary by id

curl -X "DELETE" "https://sandbox-api.openpayd.com/api/v1/beneficiaries/12345678-1234-5678-1234-567812345678" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'
Delete beneficiary by external id
DELETE /beneficiaries/external/{id}

Deletes the beneficiary account specified by the external id. This endpoint uses the same request and response structure as delete beneficiary by id but uses the externalId instead.

Path variables

id
string required

External id of the beneficiary to be deleted

Conversion
POST /conversions/quotes
POST /conversions
GET /conversions/
GET /conversions/{id}
GET /conversions/external/{id}
Create a conversion quote
POST /conversions/quotes

Create a conversion quote between two currencies. This quote can then be used to convert to the desired currency.

Request parameters

buyCurrency
string required

Three letter currency code of the currency to convert to

sellCurrency
string required

Three letter currency code of the currency to convert from

fixedSide
string required

buy or sell

amount
number required

The amount of the fixed buy or sell currency

conversionDate
string required

Date of conversion (i.e. 2017-12-31)

onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

Responses

200 OK
Body
Object
id
string

Internal quote id

buyCurrency
string

Currency to buy. Currency account must be active and supported.

sellCurrency
string

Currency to sell. Currency account must be active and supported.

buyAmount
number

Amount to buy after conversion

sellAmount
number

Amount to sell

fixedSide
string

buy or sell

midMarketRate
string

Market rate

offeredRate
string

Offered rate

expirationDateTime
string

Time at which this conversion quote will expire

settlementCutOffDateTime
string

Time at which this quote needs to settle by

Example request
Example response

sample request to create a quote

curl -X "POST" "https://sandbox-api.openpayd.com/api/v1/conversions/quotes" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' \
     -H 'Content-Type: text/plain; charset=utf-8' \
     -d $'{
  "buyCurrency": "USD",
  "sellCurrency": "GBP",
  "amount": "10.00",
  "fixedSide": "buy",
  "conversionDate": "2018-03-16"
}'

sample response to create a quote

{"id":"08daf41a-7f3f-4a08-945e-e636d4c6e68b",
 "buyCurrency":"USD",
 "sellCurrency":"GBP",
 "buyAmount":10,
 "sellAmount":7.18,
 "fixedSide":"buy",
 "midMarketRate":0.717,
 "offeredRate":0.7177,
 "expirationDateTime":"2018-03-16T12:54:40.090",
 "settlementCutOffDateTime":"2018-03-16T15:00:00.000"}
Create a conversion
POST /conversions

Once a conversion quote is ready, a conversion operation can be initiated to convert between currencies.

For sandbox testing, create a conversion call should be performed within 20 seconds of receiving a conversion quote. After 20 seconds, conversion quote will expire.

Request body

Object
quoteId
string required

id returned from the create a quote call

termAgreement
string required

true or false

externalId
string required

Client generated unique reference number

onBehalfOf
string

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

Responses

200 OK
Body
Object
id
string

Conversion id

transactionReference
string

OpenPayd system reference number in human readable format

sellAmount
string

Amount sold

buyAmount
string

Amount bought

sellCurrency
string

Currency sold

buyCurrency
string

Currency bought

offeredRate
string

Rate used to perform conversion

midMarketRate
string

Market conversion rate

settlementDateTime
string

Time and date of settlement

externalId
string

Client generated unique reference number

creationDateTime
string

Time and date when conversion created

clientId
string

Id of the client that performed the conversion

Example request
Example response

sample request to create a conversion

 curl -X "POST" "https://sandbox-api.openpayd.com/api/v1/conversions" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "quoteId": "4d0234e7-e338-4726-903a-e8899f932507",
  "termAgreement": "true",
  "externalId": "123434"
}'

sample response to create a conversion

{
    "id": "d1b86be6-fb36-4a85-a448-a1b939153ec4",
    "externalId": "123434",
    "transactionReference": "20190702-9Z3079",
    "sellAmount": 660,
    "buyAmount": 89.03,
    "sellCurrency": "TRY",
    "buyCurrency": "EUR",
    "offeredRate": 0.134906458,
    "midMarketRate": 0.157025,
    "settlementDateTime": "2019-07-02T22:00:00.000",
    "creationDateTime": "2019-07-02T15:42:44.878",
    "clientId": "6bc804fc-dfb8-403f-a67d-3ba7f4abdd67"
}
List conversions
GET /conversions/

Returns a list of conversions initiated by the OpenPayd user.

Request parameters

pageNumber
string required
Example:
1
pageSize
string required
Example:
100
scope
string optional

Listing scope

Enumeration:
all

list everything (owned by main client and linked clients)

main

owned by main client

linked

owned by the linked client specified on “onBehalfOf” parameter

Default:
all

Request body

Following request parameters are optional, they can be used to filter returned results.

Object
sellCurrency
string

Three letter currency code of the currency sold.

buyCurrency
string

Three letter currency code of the currency bought.

minSellAmount
number

Filter results by minimum amount sold.

maxSellAmount
string

Filter results by maximum amount sold.

minBuyAmount
number

Filter results by minimum amount bought.

maxBuyAmount
number

Filter results by maximum amount bought.

status
string
Enumeration:
pending_awaiting_funds
completed
canceled
minSettlementDate
string

Filter results by settlement date from requested date onwards.

maxSettlementDate
string

Filter results by settlement date until requested date.

minCreationDate
string

Filter results by creation date from requested date onwards.

maxCreationDate
string

Filter results by creation date until requested date.

transactionReference
string

Filter results by reference number

onBehalfOf
string

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

Responses

200 OK
Body
Object
id
string

Internal conversion id

transactionReference
string

OpenPayd system reference number in human readable format

sellCurrency
string

Currency sold

buyCurrency
string

Currency bought

sellAmount
number

Currency amount sold

buyAmount
number

Currency amount bought

status
string

Conversion operation status

offeredRate
string

Rate applied to conversion

midMarketRate
string

Market conversion rate

creationDateTime
string

Time and date when conversion created

settlementDateTime
string

Time and date when conversion settled

completionDateTime
string

Time and date when conversion completed

externalId
string

Client generated unique reference number

clientId
string

Id of the client that performed the conversion

Example request
Example response

sample request to list conversions

curl "https://sandbox-api.openpayd.com/api/v1/conversions?pageSize=100&pageNumber=1" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'

sample response to list conversions

{"pagination": {"totalEntryCount":2,"totalPageCount":1,"currentPage":1,
 "maximumPageSize":100,"currentPageSize":2,"previousPage":0,"nextPage":0},
"conversionList":[
  "conversionList": [
        {
            "id": "d1b86be6-fb36-4a85-a448-a1b939153ec4",
            "externalId": "1222",
            "clientId": "6bc804fc-dfb8-403f-a67d-3ba7f4abdd67",
            "transactionReference": "20190702-9Z3079",
            "sellCurrency": "TRY",
            "buyCurrency": "EUR",
            "sellAmount": 660,
            "buyAmount": 89.03,
            "status": "pending_awaiting_funds",
            "offeredRate": 0.134906458,
            "midMarketRate": 0.157025,
            "creationDateTime": "2019-07-02T15:42:44.878",
            "settlementDateTime": "2019-07-02T22:00:00.000",
            "completionDateTime": null
        },
        {
            "id": "13ee1a69-b003-4286-ac63-fc3b4ad30455",
            "externalId": "122",
            "clientId": "fca29305-f9bb-4fda-8203-0025eae54bb8",
            "transactionReference": "20190626-9LD4QE",
            "sellCurrency": "TRY",
            "buyCurrency": "EUR",
            "sellAmount": 660,
            "buyAmount": 86.57,
            "status": "pending_awaiting_funds",
            "offeredRate": 0.13117865,
            "midMarketRate": 0.152686,
            "creationDateTime": "2019-06-26T08:08:06.237",
            "settlementDateTime": "2019-06-28T22:00:00.000",
            "completionDateTime": null}]}
Get conversion by id
GET /conversions/{id}

Retrieves a conversion by conversion id.

Path variables

id
string required

Conversion id

Request parameters

onBehalfOf
string optional

Id of the linked client

DEPENDS ON: If a main client is performing this call on behalf of a linked client, id of the linked client must be set on this parameter.

Responses

200 OK
Body
Object
id
string

Conversion id

externalId
string

Client generated unique reference number

transactionReference
string

OpenPayd system reference number in human readable format

sellCurrency
string

Sell currency

buyCurrency
string

Buy currency

buyAmount
number

Conversion amount

status
string

Conversion status

offeredRate
string

Conversion rate

midMarketRate
string

Market rate

creationDateTime
string

Date and time of request

settlementDateTime
string

Date and time of settlement

completionDateTime
string

Date and time of completion

Example request
Example response

sample request to get conversion by id

 curl "https://sandbox-api.openpayd.com/api/v1/conversions/347ddc6a-ea71-400c-b623-f796c159975e" \
     -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V'

sample response to get conversion by id

   "id":"347ddc6a-ea71-400c-b623-f796c159975e",
   "externalId":"123434",
   "transactionReference":"20180316-XVKOX9",
   "sellCurrency":"GBP",
   "buyCurrency":"USD",
   "sellAmount":7.18,
   "buyAmount":10.00,
   "status":"pending_awaiting_funds",
   "offeredRate":0.717700000,
   "midMarketRate":0.717000000,
   "creationDateTime":"2018-03-16T13:06:24.319",
   "settlementDateTime":"2018-03-16T15:00:00.000",
   "completionDateTime":null
Get conversion by external id
GET /conversions/external/{id}

Retrieves a conversion by external id. This endpoint uses the same request and response structure as get conversion by id but uses an externalId to retrieve the conversion.

Path variables

id
string required

External conversion id

Linked Client

OpenPayd offers its clients the ability to create linked clients, which can be used either to onboard their own clients or segregate funds and transactions. To be able to use this feature, please Contact-Us so that you are configured as a main client.

Once a linked client is created, the main client may:

  • receive money to the linked client currency account
  • send money from the linked client currency account
  • convert money between linked client currency accounts
  • transfer funds to/from/between linked clients

For a main client to perform above operations on behalf of a linked client, id of the linked client must be set to “onBehalfOf” parameter of each request.

POST /clients
GET /clients
GET /clients/{id}
Create a linked client
POST /clients

Creates a linked client for the authenticated main client.

Request body

Object
legalEntityType
string
Enumeration:
corporate
retail
legalName
string

Legal company name (required if legal entity type is corporate)

registrationNumber
string

Company registration number

incorporationDate
string

Incorporation date (required if legal entity type is corporate)

Example:
2015-11-21
legalForm
string

required if legal entity type is corporate

Enumeration:
partnership
public_limited_company
sole_trader
limited_liability
joint_stock_company
charity
industrySectorType
string

required if legal entity type is corporate

Enumeration:
travel
transport
fintech
credit
forestry
mining
exports
textiles/clothing
sports
telecom
chemical
accountancy
aerospace
agriculture
automotive
construction
digital/media/advertising
ecommerce
education
electronics
energy
entertainment
fishing
food
healthcare
hospitality
humanresources
informationtechnology
internet
luxurygoods
manufacturing
marine
payroll
pharmaceutical
publishing
pulpandpaper
retail
steel
timber
tobacco
water
other
industrySectorValue
string

If industrySectorType is other then this freetext field is populated with the client sector type

contactName
string

Name of contact person (required if legal entity type is corporate)

email
string required

Email of contact person

primaryPhoneCountry
string required

Two letter primary phone country code

Example:
TR
primaryPhoneNumber
string required

Primary phone number

registeredAddressCountry
string

Two letter address country code (required if legal entity type is corporate)

Example:
TR
registeredAddressState
string

Address state

registeredAddressPostalCode
string

Address postal code (required if legal entity type is corporate)

Example:
34330
registeredAddressCity
string

Address city (required if legal entity type is corporate)

registeredAddressLine
string

Address line (required if legal entity type is corporate)

Example:
123 Main street
residentialAddressCountry
string

Two letter address country code (required if legal entity type is retail)

Example:
TR
residentialAddressState
string

Address state

residentialAddressPostalCode
string

Address postal code (required if legal entity type is retail)

Example:
34330
residentialAddressCity
string

Address city (required if legal entity type is retail)

residentialAddressLine
string

Address line (required if legal entity type is retail)

Example:
123 Main street
firstName
string

First name of retail client (required if legal entity type is retail)

middleName
string

Middle name of retail client

lastName
string

Last name of retail client (required if legal entity type is retail)

dateOfBirth
string

date of birth of retail client (required if legal entity type is retail)

nationality
string

Two letter country code (required if legal entity type is retail)

Example:
TR
identificationType
string

required if legal entity type is retail

Enumeration:
drivers_license
passport
national_id
others
identificationValue
string

Identification number

nickname
string

Optional field for differentiating clients wtih similar attributes

Responses

200 OK
Body
Object
legalEntityType
string

corporate or retail

legalName
string

Legal name for the client

registrationNumber
string

Company registration number

incorporationDate
string

Incorporation date for the client

<