OpenPayd API Getting Started Authentication HTTP Request Postman Collection REST API Reference Data Webhook 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-sg.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. Login POST /authentication/login Logout 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" }' 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. Create a currency account POST /currency-accounts List currency accounts GET /currency-accounts Get currency account GET /currency-accounts/{currency} List Balance Histories GET /currency-accounts/balance-history Get pay-in GET /pay-ins/{id} List pay-in 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 Iban for the bank account show more 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" }' 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. If a main client is performing this call to list its all linked clients, onBehalfOf parameter shouldn’t be sent scope String optional Listing scope DEPENDS ON: If a main client is performing this call to list its all linked clients, scope parameter shouldn’t be sent 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 show more 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' 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 Bank account IBAN number show more 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' show more 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 $'{}' 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 show more 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' 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 show more 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' Payment Create payment POST /payments Validate payment POST /payments/validate List payments GET /payments Get payment by id GET /payments/{id} Get payment by external id GET /payments/external/{id} Cancel payment by id POST /payments/{id}/cancel Cancel payment by external id 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 swift express_swift reasonCode String required Enumeration: personal show more 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 show more 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" } show more 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 show more 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" } 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 show more 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 show more 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' 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 show more 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' 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 show more 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", show more 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. Create a beneficiary POST /beneficiaries Validate beneficiary POST /beneficiaries/validate List beneficiaries GET /beneficiaries Get beneficiary by id GET /beneficiaries/{id} Get beneficiary by external id GET /beneficiaries/external/{id} Update beneficiary POST /beneficiaries/{id} Delete beneficiary by id DELETE /beneficiaries/{id} Delete beneficiary by external 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 City show more 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 show more 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", : } ], : , : , : }' show more 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 State of country show more 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", : } ], : , : , }' show more 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 $'{}' 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 show more 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' 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 show more 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 show more 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", : , : , : , : }' show more 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 MT103 End Point for uploading MT103 file Uplaod MT103 file POST /spapi/payments/end-of-day Uplaod MT103 file POST /spapi/payments/end-of-day You can use to upload MT103 files. You do not need to login for this api. Please ask for api key from support. Request parameters file String optional Multipart Data Request headers X-INSTANCE-API-KEY String optional Api Key Responses 201 Created Conversion Create a conversion quote POST /conversions/quotes Create a conversion POST /conversions List conversions GET /conversions/ Get conversion by id GET /conversions/{id} Get conversion by external 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 show more 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" }' 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 show more 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" }' 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 show more 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 show more 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' 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 show more 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' 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. Create a linked client POST /clients List linked clients GET /clients Get linked client 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 show more 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 legalForm String Enumeration: partnership public_limited_company sole_trader limited_liability joint_stock_company charity industrySectorType Enumeration: show more Example request(Corporate Client) Example response(Corporate Client) Example request(Retail Client) Example response(Retail Client) sample request to create a linked corporate client curl -X POST \ https://sandbox-api.openpayd.com/api/v1/clients \ -H 'Content-Type: application/json' \ -H 'X-AUTH-TOKEN: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' \ -d '{ "legalEntityType": "corporate", "legalName": "TESTLAPTOP INC. 220", "registrationNumber": "1011010", "incorporationDate": "2015-11-21", "legalForm": "partnership", "industrySectorType": "fintech", "industrySectorValue": null, "contactName": "simulator", "email": "elif@efttesting.com", "primaryPhoneCountry": "TR" , "primaryPhoneNumber":"2130", "registeredAddressCountry": "TR", "registeredAddressState": null, "registeredAddressCity": "İstanbul", "registeredAddressPostalCode": 12345, "registeredAddressLine": "Kayapalas Apt. Registered", }' show more List linked clients GET /clients Lists the linked clients for the main client. Request parameters pageNumber String required Example: 1 pageSize String required Example: 100 status String optional Enumeration: active inactive pending nickname String optional Optional field for differentiating clients wtih similar attributes internalId Number optional Internal id of a client that is wanted to search Responses 200 OK Response will include an array of the below response object Body Object id String Client id legalName String Legal name for the client email String Client email address status String Client status type String Client type firstName String First name of retail client middleName String Middle name of retail client lastName String Last name of retail client nickname String Optional field for differentiating clients wtih similar attributes Example request Example response sample request to list linked clients curl -X GET \ 'https://sandbox-api.openpayd.com/api/v1/clients?pageSize=10&pageNumber=1' \ -H 'X-AUTH-TOKEN: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' Get linked client GET /clients/{id} Returns the linked client by the specified client id. Path variables id String required Linked client id Responses 200 OK Body Object id String Client id legalName String Legal name for the client email String Email address status String Client status legalEntityType String corporate or retail contactName String Contact person name registrationNumber String Company registration number primaryPhoneCountry String Two letter phone country code show more Example request Example response sample request to get a linked client curl -X GET \ https://sandbox-api.openpayd.com/api/v1/clients/c1bb6e08-cb58-4509-b1e6-bfb77a1037fc \ -H 'X-AUTH-TOKEN: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' Transfer Transfer endpoint is used to transfer funds between the linked client currency accounts. Create a transfer POST /transfers List transfers GET /transfers Get transfer by id GET /transfers/{id} Get transfer by external id GET /transfers/external/{id} Create a transfer POST /transfers Creates a transaction to transfer funds between linked clients. Only main clients have the permission to create a transfer transaction. Request body Object amount Number required Transaction amount currency String required Three letter currency code. Currency account must be active and supported. Example: GBP receiverClientId String required Client id that will receive the funds externalId String required User specified external reference id 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. transferReference String User specified reference number transferReason String User specified reason for fund transfer Responses 200 OK Body Object amount String Transaction amount currency String Three letter currency code id String Transfer transaction id externalId String User specified external id senderClientId String Client id that is transferring the funds receiverClientId String Client id that is receiving the funds transferReference String User specified reference number transferReason String User specified reason for transfer show more Example request Example response sample request to create a transfer transaction curl -X POST \ https://sandbox-api.openpayd.com/api/v1/transfers \ -H 'Content-Type: application/json' \ -H 'X-AUTH-TOKEN: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' \ -d '{ "currency": "GBP", "amount": 20, "receiverClientId": "c1bb6e08-cb58-4509-b1e6-bfb77a1037fc", "externalId": "REF14" }' List transfers GET /transfers Lists the transfers performed by the authenticated main client. 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. 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 Response will be an array of the below response object Body Object id String Transfer transaction id externalId String User specified external id for the transaction senderClientId String Client that is transferring the funds receiverClientId String Client that is receiving the funds currency String Three letter currency code amount String Amount of transfer transferReference String User specified reference number for the transfer transferReason String User specified reason for transfer show more Example request Example response sample request to list transfers curl -X GET \ 'https://sandbox-api.openpayd.com/api/v1/transfers?pageSize=10&pageNumber=1' \ -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' Get transfer by id GET /transfers/{id} Retrieves the transfer specified by the transfer id. Path variables id String required Transfer 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 Transfer transaction id externalId String User specified external id for the transaction senderClientId String Client id transferring the funds receiverClientId String Client id receiving the funds currency String Three letter currency code amount String Transfer amount transferReference String User specified reference number transferReason String User specified reason for transfer show more Example request Example response sample request to get a transfer by id curl -X GET \ https://sandbox-api.openpayd.com/api/v1/transfers/09be83ea-bc49-4064-a50a-e5b933ebd26a \ -H 'X-AUTH-TOKEN: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' Get transfer by external id GET /transfers/external/{id} Retrieves the transfer transaction by the specified external id. Path variables id String required External reference id for the transfer 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 Transfer id externalId String User-specified external id for the transfer senderClientId String Client id transferring the funds receiverClientId String Client id receiving the funds currency String Three letter currency code amount String Transfer amount transferReference String User specified reference number transferReason String User specified reason for transfer show more Example request Example response sample request to get transfer by external id curl -X GET \ https://sandbox-api.openpayd.com/api/v1/transfers/external/REF14 \ -H 'X-AUTH-TOKEN: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' Reference Data Beneficiary required details GET /reference/beneficiary-required-details List payment dates GET /reference/payment-dates List conversion dates GET /reference/conversion-dates Beneficiary required details GET /reference/beneficiary-required-details This endpoint provides the required bank information to create a beneficiary. Bank accounts of different countries require different bank account information to route money. This endpoint provides the required information for the country and bank specified in the request. Request parameters beneficiaryCountry String optional Beneficiary account country currency String required Three letter currency code of the account bankAccountCountry String required Bank country beneficiaryType String required corporate or retail Responses 200 OK Body Object metadataList Array Object paymentType String express or standard addressRequired Boolean true or false accountNumber String account number regex Example: ^\\d{8}$ iban String iban regex Example: ^[a-zA-Z]{2}[0-9]{2}[a-zA-Z0-9]{8}([a-zA-Z0-9]?){3,19}$|^[A-Z]{2}\\d{5}[0-9A-Z]{13}$ bic String bic regex Example: ^[0-9A-Z]{8}$|^[0-9A-Z]{11}$ beneficiaryFirstName String required if account type is retail Example: ^.{1,255} beneficiaryLastName String required if account type is retail Example: ^.{1,255} beneficiaryBirthDate String required if account type is retail companyName String required if account type is corporate Example: ^.{1,255} beneficiaryType String retail or corporate routingCodeType String Example: sort_code routingCodeFormat String Example: ^\\d{6}$ bankName String bankAccountType String taxId String Example request Example response sample request to get required beneficiary details curl "https://sandbox-api.openpayd.com/api/v1/reference/beneficiary-required-details?beneficiaryCountry=GB&currency=GBP&bankAccountCountry=GB&beneficiaryType=corporate" \ -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' Currency codes List currency codes GET /reference/currencies Get currency GET /reference/currencies/{code} List currency codes GET /reference/currencies Returns the list of currencies supported by OpenPayd. Available currencies might be different in live environment. Please contact your account manager for details. Responses 200 OK Successful response will return an array of below response body. Body Object code String Three letter currency code name String Name of currency decimalPlace Number Number of decimal places used for currency Example request Example response sample request to list supported currencies curl "https://sandbox-api.openpayd.com/api/v1/reference/currencies" \ -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2VjQGNvZGVzcGFjZWRldi5jb20iLCJpbnN0YW5jZUlkIjoiMSIsInJvbGUiOlsiVVNSIl0sImNoYW5uZWwiOiJBUEkiLCJzZXNzaW9uSWQiOiJjOTMxZmE4ZC02Y2M5LTQwYjQtYWNkNy1mMTk5MzQzOWNjNjAiLCJsb2dpbkV2ZW50SWQiOiI4MDQiLCJ0eXBlIjoiMSIsImV4cCI6MTUyMDU3OTI3NywidXNlcklkIjoiMTE3IiwiaWF0IjoxNTIwNTc1Njc3fQ.2anMgUu8cc1g7a2zTF5Rt2nc5y7gYopwoZ0s-TysTrECLRSCw2MF1BzYJQ_kwx9rjvaM-7AorljspEzgHYrZPw' \ -H 'Content-Type: application/json; charset=utf-8' \ -d $'{}' show more Get currency GET /reference/currencies/{code} Retrieves a currency by the specified currency code. Path variables code String required Responses 200 OK Successful response will return an array the below response body. Body Object code String Three letter currency code name String Currency name decimalPlace Number Number of decimal places used for currency Example request Example response sample request to get a currency curl "https://sandbox-api.openpayd.com/api/v1/reference/currencies/GBP" \ -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' Country codes List country codes GET /reference/countries Get country GET /reference/countries/{alpha2Code} List state & province codes GET /reference/countries/{alpha2Code}/states Get state or province GET /reference/countries/{alpha2Code}/states/{code} List country codes GET /reference/countries Returns a list of supported countries. Responses 200 OK Successful response will return an array of below response body. Body Object alpha2Code String Two letter alpha country code alpha3Code String Three letter alpha country code numericCode Number Three digit numeric country code dialInCode Number Country dial in code name String Country name Example request Example response sample request to list supported countries curl "https://sandbox-api.openpayd.com/api/v1/reference/countries" \ -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' Get country GET /reference/countries/{alpha2Code} Returns the country by the specified alpha code. Path variables alpha2Code String required Two letter country code Responses 200 OK Body Object alpha2Code String Alpha 2 code of the country Example: US alpha3Code String Alpha 3 code of the country Example: USA numericCode String Numeric code of the country Example: 840 dialInCode String Dial in code of the country Example: 1 name String Name of country Example: United States of America Example request Example response sample request to get a country curl "https://sandbox-api.openpayd.com/api/v1/reference/countries/US" \ -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' List state & province codes GET /reference/countries/{alpha2Code}/states Returns the list of states or provinces for the specified country. Path variables alpha2Code String required Two letter country code Responses 200 OK Body Object code String State code name String Name of state countryAlpha2Code String Two letter country code Example request Example response sample request to list states curl "https://sandbox-api.openpayd.com/api/v1/reference/countries/US/states" \ -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' Get state or province GET /reference/countries/{alpha2Code}/states/{code} Path variables alpha2Code String required code String required Responses 200 OK Body Object code String Two letter country code name String Name of state or province countryAlpha2Code String Two letter country code Example request Example response sample request to get a state or province curl "https://sandbox-api.openpayd.com/api/v1/reference/countries/US/states/MD" \ -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' List payment dates GET /reference/payment-dates Returns the first available payment date along with a list of dates when payments cannot be made (i.e. bank holidays). Request parameters currency String required Three letter currency code Responses 200 OK Body Object firstAvailablePaymentDate String First day that the payment can go through Example: 2018-03-19 unavailablePaymentDateList Array List of offline days when payments cannot go through String String Example request Example response sample request to get payment dates curl "https://sandbox-api.openpayd.com/api/v1/reference/payment-dates?currency=GBP" \ -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' \ -H 'Content-Type: application/json; charset=utf-8' \ -d $'{}' List conversion dates GET /reference/conversion-dates Returns the first available conversion date along with a list of dates when currency conversions cannot be completed (i.e. bank holidays). Request parameters currencyPair String required Three letter currency code pair to convert Example: GBPUSD Responses 200 OK Body Object firstAvailableConversionDate String mandatoryConversionDate String unavailableConversionDateList Array Dates when conversions cannot go through String String Example request Example response sample request to get conversion dates curl "https://sandbox-api.openpayd.com/api/v1/reference/conversion-dates?currencyPair=GBPUSD" \ -H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWlyLnl1cmRhZ2V' Webhook Webhooks are HTTP callbacks that receive notification messages for events. Webhooks allow to notify client side when an event has occurred in the platform, so the client can take the corresponding actions without making any polling request. They are also called as Reverse API. Integration Steps 1-Configuring Webhook Listener A webhook listener is a server that listens at a specific URL for incoming HTTP POST notification messages that are triggered when events occur. You can create and configure one listener for all webhook events or separate listeners specific to each event. After you configure a listener, note the URL for the listener to subscribe related webhook type. 2-Verifying Webhook Notifcation Request OpenPayd signs each webhook message that it delivers to your webhook listener. You must verify DigitalSignature header with OpenPayd public key and request body. The public key can be downloaded from the webhook configuration screen. You are able to verify that it is OpenPayd who sent the webhook message by implementing these steps. 3-Signing Webhook Notifcation Response OpenPayd sends nonce value inside of the webhook message body to differentiate repeated requests having the same reference values. This nonce value also using as another verification mechanism and DigitalSignature value changer for repeated webhook calls. Your response to the webhook message request must contain that nonce value. Also, you have to use the body containing that nonce value at DigitalSignature generation as explained below. Webhook Message Response Creation Steps; Take the Nonce number from the Webhook Request Place the Nonce into the body of the response, for example “{“nonce”: <value>}”. Hash the response body, using SHA 256. Sign the hash with your Private Key. Attach the signed hash as Base64 encoded in the DigitalSignature Response Header. 4-Uploading Your Public Key You must upload your public key as a csr file from the webhook configuration screen before subscribing for any webhook type. By using your public key, response object’s nonce value and DigitalSignature header OpenPayd can verify the response is really coming from you. 5-Subscribing to Webhook Events You can subscribe your webhook listener/listeners to webhook configuration events from webhook configurations screen. 6-Testing your Integration In order to test your integration end to end, you must first subscribe for an event called Test Event. This event is just for testing the all integration process and can be easily triggered via the webhook configuration screen. Webhook Response Object Generic response object for all webhook notifications. Object webhookType String type of webhook Example: WHTEST webhookReference String unique reference for each notification Example: 9a0474e0-d578-4335-953f-cbe0d465f25b nonce String random digits to differentiate calls Example: 732448 payload Object Payload object that changes by webhook type message String Example: Just for test clientId String Example: b19f0724-dc79-4f2c-9b39-6c5972defad6 Example 1 { "webhookType": "WHTEST", "webhookReference": "9a0474e0-d578-4335-953f-cbe0d465f25b", "nonce": "732448", "payload": { "message": "Just for test", "clientId": "b19f0724-dc79-4f2c-9b39-6c5972defad6" } } Webhook Types Types of webhooks supported by our sytem. Test Event Event type to test integration from end to end. Representative code is WHTEST. Test Event Payload Payload object for Webhook Test Event. Object message String Example: Just for test clientId String Example: fca29305-f9bb-4fda-8203-0025eae54bb8 Example 1 { "message": "Just for test", "clientId": "fca29305-f9bb-4fda-8203-0025eae54bb8" } Currency Account Created Event that notifies after currency account creation. Representative code is ACCCRE. Currency Account Payload Payload object for Currency Account Created Event. Object status String Example: active balance String Example: 0.00 clientId String Example: fca29305-f9bb-4fda-8203-0025eae54bb8 currency String Example: HRK Example 1 { "status": "active", "balance": "0.00", "clientId": "fca29305-f9bb-4fda-8203-0025eae54bb8", "currency": "HRK" } Currency Account Status Update Event that triggers after currency account status updates. Representative code is ACCSUP. Currency Account Payload Payload object for Currency Account Status Update Event. Object status String Example: inactive balance String Example: 0.00 clientId String Example: 6bc804fc-dfb8-403f-a67d-3ba7f4abdd67 currency String Example: USD Example 1 { "status": "inactive", "balance": "0.00", "clientId": "6bc804fc-dfb8-403f-a67d-3ba7f4abdd67", "currency": "USD" } Client Created Event that notifies after client creation. Representative code is CLICRE. Client Payload Payload object for Client Created Event. Object id String legalName String email String status String legalEntityType String contactName String registrationNumber String primaryPhoneCountry show more Example 1 { "id": "2db2cd2f-e1ec-4715-84ac-fab923d88538", "email": "web@com.com", "status": "active", "lastName": null, "nickname": "", "firstName": null, "legalForm": "public_limited_company", "legalName": "wep", "middleName": null, "contactName": "web@com.com", "dateOfBirth": null, "nationality": null, "legalEntityType": "corporate", "incorporationDate": "2019-05-05", "identificationType": null, "industrySectorType": "chemical", "primaryPhoneNumber": "123123", "registrationNumber": "", "identificationValue": "", "industrySectorValue": "", "primaryPhoneCountry": "AL", "registeredAddressCity": "İstanbul", "registeredAddressLine": "Mecidiyeköy", "registeredAddressState": null, "residentialAddressCity": null, "residentialAddressLine": null, show more Client Status Update Event that notifies after client status updates. Representative code is CLISUP. Client Payload Payload object for Client Status Update Event. Object id String legalName String email String status String legalEntityType String contactName String registrationNumber String primaryPhoneCountry show more Example 1 { "id": "2db2cd2f-e1ec-4715-84ac-fab923d88538", "email": "web@com.com", "status": "active", "lastName": null, "nickname": "", "firstName": null, "legalForm": "public_limited_company", "legalName": "wep", "middleName": null, "contactName": "web@com.com", "dateOfBirth": null, "nationality": null, "legalEntityType": "corporate", "incorporationDate": "2019-05-05", "identificationType": null, "industrySectorType": "chemical", "primaryPhoneNumber": "123123", "registrationNumber": "", "identificationValue": "", "industrySectorValue": "", "primaryPhoneCountry": "AL", "registeredAddressCity": "İstanbul", "registeredAddressLine": "Mecidiyeköy", "registeredAddressState": null, "residentialAddressCity": null, "residentialAddressLine": null, show more Pay In Status Update Event that notifies after pay in transaction status updates. Representative code is PAISUP. Pay In Payload Payload object for Pay In Status Update Event. Object id String status String clientId String amount String currency String transactionReference String transactionDateTime String senderName show more Example 1 { "id": "bbabf8e6-475f-469c-b440-e859e2551ed5", "status": "Completed", "amount": 1000, "clientId": "f3580edc-2ceb-4b54-9ef0-a8059fd302b9", "currency": "USD", "senderBic": null, "senderIban": null, "senderName": null, "senderAddress": null, "senderInformation": null, "transactionDateTime": "2019-05-03T11:30:12.941", "transactionReference": "20190503-9L3KDV" } Transfer Status Update Event that notifies after transfer transactions status updates. Representative code is TRASUP. Transfer Payload Payload object for Transfer Status Update Event. Object id String clientId String externalId String senderClientId String receiverClientId String currency String amount Number transferReference show more Example 1 { "id": "98314a37-32e5-4cff-98f0-70d0e981363a", "amount": 500, "clientId": "2ff197d0-36a0-453f-8e0a-0b6d6241ff0d", "currency": "EUR", "externalId": null, "senderClientId": "2ff197d0-36a0-453f-8e0a-0b6d6241ff0d", "transferReason": "ads", "receiverClientId": "350d28f4-2264-493d-8451-3299acd9b51f", "transferReference": "20190506-94ZXQV", "transactionReference": "sadasd", "status": "completed" } IBAN Assigned Event type that notifies after the IBAN assignment. Representative code is IBANAS. IBAN Assigned Payload Payload object for IBAN Assigned Event. Object clientId String currency String status String balance Number bankName String bankAccountHolderName String accountNumber String bicSwift show more Example 1 { "iban": "EE767777000202566375", "status": "active", "balance": 0, "bankName": null, "bicSwift": "LHVBEE22", "clientId": "8f9ab328-922f-4303-80cc-69c7f06272f0", "currency": "CAD", "bankAddress": null, "bankCountry": "EE", "accountNumber": null, "routingCodeList": null, "bankAccountHolderName": "Auto Clear" } Payment Created Event that notifies after pay out transactions status updates. Representative code is PAYCRE. Payment Payload Payload object for Payment Created Event. Object id String clientId String externalId String currency String amount Number paymentDate String beneficiaryId String paymentType show more Payment Rolled Event type that notifies after pay out transactions rolled. Representative code is PAYROL. Payment Payload Payload object for Payment Rolled Event. Object id String clientId String externalId String currency String amount Number paymentDate String beneficiaryId String paymentType show more Payment Status Update Event type that notifies after pay out transactions status updates. Representative code is PAYSUP. Payment Payload Payload object for Payment Status Event. Object id String clientId String externalId String currency String amount Number paymentDate String beneficiaryId String paymentType show more Conversion Created Event type that notifies after conversion transaction created. Representative code is CONCRE. Conversion Payload Payload object for Conversion Created Event. Object id String clientId String externalId String transactionReference String sellCurrency String buyCurrency String sellAmount Number buyAmount show more Example 1 { "id": "a160b23b-80a3-46d0-99fd-966b5a05d81e", "status": "pending_awaiting_funds", "clientId": "350d28f4-2264-493d-8451-3299acd9b51f", "buyAmount": 119.8, "externalId": null, "sellAmount": 120, "buyCurrency": "EUR", "offeredRate": 0.998406594, "sellCurrency": "GBP", "midMarketRate": 1.1621, "creationDateTime": "2019-05-09T07:42:30.963", "completionDateTime": null, "settlementDateTime": "2019-05-09T22:00:00.000", "transactionReference": "20190509-95XPWV" } Conversion Rolled Event that triggers after conversion transactions rolled. Representative code CONROL. Conversion Payload Payload object for Conversion Rolled Event. Object id String clientId String externalId String transactionReference String sellCurrency String buyCurrency String sellAmount Integer buyAmount show more Example 1 { "id": "null", "status": "pending_awaiting_funds", "clientId": "350d28f4-2264-493d-8451-3299acd9b51f", "buyAmount": 129.84, "externalId": null, "sellAmount": 130, "buyCurrency": "EUR", "offeredRate": 0.998836164, "sellCurrency": "GBP", "midMarketRate": 1.1626, "creationDateTime": "2019-05-09T07:58:18.653", "completionDateTime": null, "settlementDateTime": "2019-05-09T22:00:00.000", "transactionReference": "20190509-VO7XJV" } Conversion Status Update Event that triggers after conversion transactions status updates. Representative code CONSUP. Conversion Payload Payload object for Conversion Status Update Event. Object id String clientId String externalId String transactionReference String sellCurrency String buyCurrency String sellAmount Integer buyAmount show more Example 1 { "id": "92e46bea-7cb3-4a03-b428-9b5ba562ef98", "status": "canceled", "clientId": "350d28f4-2264-493d-8451-3299acd9b51f", "buyAmount": 129.84, "externalId": null, "sellAmount": 130, "buyCurrency": "EUR", "offeredRate": 0.998836164, "sellCurrency": "GBP", "midMarketRate": 1.1626, "creationDateTime": "2019-05-09T07:58:18.653", "completionDateTime": null, "settlementDateTime": "2019-05-09T22:00:00.000", "transactionReference": "20190509-VO7XJV" } Beneficiary Created Beneficiary Payload Payload object for Beneficiary Created Event. Object properties id String Example: 5f9909c9-3eb1-4269-bc0b-d06e077dabce bic String Example: ANTSGB2L iban String Example: GB73CLRB04050900000400 name String Example: TEST bankName Unknown nullable clientId String Example: 50a5bf9c-26f4-4f58-8855-37058d3255e7 currency String Example: EUR externalId show more Example 1 { "id": "5f9909c9-3eb1-4269-bc0b-d06e077dabce", "bic": "ANTSGB2L", "iban": "GB73CLRB04050900000400", "name": "TEST", "bankName": null, "clientId": "50a5bf9c-26f4-4f58-8855-37058d3255e7", "currency": "EUR", "externalId": null, "bankAddress": null, "companyName": "TEST", "accountNumber": null, "beneficiaryCity": null, "beneficiaryType": "corporate", "paymentTypeList": [ "sepa" ], "routingCodeList": null, "beneficiaryState": null, "creationDateTime": "2019-09-24 14:21:49", "bankAccountCountry": "GB", "beneficiaryCountry": "GB", "beneficiaryLastName": null, "beneficiaryBirthDate": null, "beneficiaryFirstName": null, "bankAccountHolderName": "test", "beneficiaryPostalCode": null, show more Beneficiary Updated Beneficiary Payload Payload object for Beneficiary Updated Event. Object id String Example: 5f9909c9-3eb1-4269-bc0b-d06e077dabce bic String Example: ANTSGB2L iban String Example: GB73CLRB04050900000400 name String Example: TEST bankName Unknown nullable clientId String Example: 50a5bf9c-26f4-4f58-8855-37058d3255e7 currency String Example: EUR externalId show more Example 1 { "id": "5f9909c9-3eb1-4269-bc0b-d06e077dabce", "bic": "ANTSGB2L", "iban": "GB73CLRB04050900000400", "name": "TEST", "bankName": null, "clientId": "50a5bf9c-26f4-4f58-8855-37058d3255e7", "currency": "EUR", "externalId": null, "bankAddress": null, "companyName": "TEST", "accountNumber": null, "beneficiaryCity": null, "beneficiaryType": "corporate", "paymentTypeList": [ "sepa" ], "routingCodeList": null, "beneficiaryState": null, "creationDateTime": null, "bankAccountCountry": "GB", "beneficiaryCountry": "GB", "beneficiaryLastName": null, "beneficiaryBirthDate": null, "beneficiaryFirstName": null, "bankAccountHolderName": "testT", "beneficiaryPostalCode": null, show more Beneficiary Deleted Beneficiary Payload Payload object for Beneficiary Deleted Event. Object id String Example: 5f9909c9-3eb1-4269-bc0b-d06e077dabce clientId String Example: 50a5bf9c-26f4-4f58-8855-37058d3255e7 externalId Unknown nullable Webhook Re-Try Policy Webhook notification resending is limited by period and maximum time. Failed webhook requests can only send again after 15 minutes and the retry process can only last 24 hours.