2. Deposit API
Deposit API is a REST API used to perform financial and non-financial transactions. You can use this API after authorization only by adding an Authorization Bearer header in each request.
InitPayment is the main request to the OPP system. It should be executed regardless of what payment solution (Credit Card or eWallet) or what flow (3DS or not) you are going to execute.
In general, payment behavior is configured on the terminal level by the OPP support team and there are no parameters that you can send to change the predefined flow.
According response status code your system should decide what the should be next step.
Please, see the list of all possible status codes in Appendix B.
To execute InitPayment, use a URL formatted as
<Deposit API URL>/payment/initializePayment
Url Example:
https://{Gateway Trx Domain}/payment/initializePayment
2.1.1.3. Request Parameters
Parameter Name | Required | Format | Description |
---|---|---|---|
merchantId | Yes | Integer | The unique identifier of the merchant processing the transaction. |
storeId | Yes | Integer | The unique identifier of the store where the transaction is initiated. |
terminalKey | No | String | A unique identifier assigned to a specific payment terminal for transaction processing. |
payerDetails | Yes | Object | See paragraph 2.1.1.3.1. |
billingAddress | Yes | Object | See paragraph 2.1.1.3.2. |
payerDevice | Yes | Object | See paragraph 2.1.1.3.3. |
paymentInstrument | No | Object | See paragraph 2.1.1.3.4. |
initialTransactionDetails | Yes | Object | See paragraph 2.1.1.3.5. |
additionalParameters | Yes | Array of objects | Extra fields are required for the specific payment method. |
signature | Yes | String | Hashed input data. See paragraph 2.2.4 for explanation. |
{
"merchantId": 900020,
"storeId": 700010,
"terminalKey": "600503",
"payerDetails": {},
"billingAddress": {},
"payerDevice": {},
"paymentInstrument": {},
"initialTransactionDetails": [{}],
"additionalParameters": {},
"signature": "{{signature}}"
}
"payerDetails": {
"firstName": "Bob",
"lastName": "Dou",
"email": "test@test.tech",
"phone": "+35799000000"
},
2.1.1.3.2. Object billingAddress
Parameter Name | Required | Format | Description |
---|---|---|---|
street | Yes | String (100) | Payer billing address street |
city | Yes | String(100) | Payer billing address city |
state | Yes | String (100) | Payer billing address state |
country | Yes | String (2) | Payer billing address country, ISO 2 |
zip | Yes | String (10) | Payer billing address zip code |
"billingAddress": {
"street": "Address",
"city": "City",
"state": "state",
"country": "CY",
"zip": "8541"
},
"payerDevice": {
"ip": "192.89.101.198"
},
2.1.1.3.4. Object paymentInstrument
*Required only for card transactions.
Parameter Name | Required | Format | Description |
---|---|---|---|
customerAccountNumber | No | String | Card number |
customerAccountName | No | String | The cardholder's name printed on the card |
securityCode | No | String | Card CVV |
expirationMonth | No | String (2) | Card expiration month |
expirationYear | No | String (4) | Card expiration year |
"paymentInstrument": {
"customerAccountNumber": "4141000000000407",
"customerAccountName": "bob",
"securityCode": "123",
"expirationMonth": "12",
"expirationYear": "2025"
},
2.1.1.3.5. Object initialTransactionDetails
Parameter Name | Required | Format | Description |
---|---|---|---|
orderId | Yes | String (32) | Merchant's unique transaction ID |
serviceName | Yes | String (100) | Free text describing the merchant’s service |
originalCurrency | Yes | String (3) | Currency of transaction, ISO 3 |
originalAmount | Yes | String (100) | The requested amount is a decimal number. |
"initialTransactionDetails": {
"orderId": "{{guid}}",
"serviceName": "Purchase of something",
"originalCurrency": "EUR",
"originalAmount": "77" //1-authorized, 2-pending
},
2.1.1.3.6. Request data signature
The signature is a means of security to ensure that the merchant is the real sender of the request. It is generated by concatenating the set of parameters separated by “;” and generating a SHA512 Hash (HEX) of the string. Parameters participating in hashing are (the order of parameters is mandatory):
# | Description |
---|---|
1 | Merchant ID |
2 | Merchant Order ID |
3 | Request the original amount |
4 | Request original currency (upper case) |
5 | Terminal ID |
6 | Payer email |
7 | Secret key (provided by the Obtained key) |
SHA512(<merchant id>; <store id>:<order id>:<amount>:<currency>; <email>; <secret>)
Parameter Name | Format | Description |
---|---|---|
token | String | A unique token identifies the transaction. |
status | Integer | Transaction status. See Appendix B for all possible statuses. |
redirectURL | String | URL is where your system should take the end user. Use it only in case it has some value. |
success | Boolean | Indicates whether the request was successfully processed (true or false). |
errorCode | Integer | Error code. See Appendix A. |
errorMessage | String | A message describing the error (if any); null if no error. |
{
"data": {
"token": "112750b7-7a6f-4446-80bf-10297b523f11",
"status": 2,
"redirectURL": "https://{Gateway Auth
Domain}/cashier/product/v1?token=112750b7-7a6f-4446-80bf-10297b523f11"
},
"success": true,
"errorMessage": null,
"errorCode": 0
}
2.1.1.5. InitPayment Raw Request Example
POST /payment/initializePayment HTTP/1.1
Content-Type: application/json
Host: -gateway.domain.io
{
"merchantId": 900059,
"storeId": 700036,
"terminalKey": "600447",
"payerDetails": {
"firstName": "Test",
"lastName": "User",
"email": "antons@yamsoft.tech",
"phone": "+35799843239"
},
"payerDevice": {
"ip": "93.109.55.32"
},
"billingAddress": {
"address": "Address",
"city": "City",
"state": "state",
"country": "CY",
"zip": "8541"
},
"paymentInstrument": {
"customerAccountNumber": "4242424242424242",
"customerAccountName": "bob",
"securityCode": "123",
"expirationMonth": "07",
"expirationYear": "2027"
},
"initialTransactionDetails": {
"orderId": "{{guid}}",
"serviceName": "serviceName",
"originalCurrency": "EUR",
"originalAmount": "1"
},
"additionalParameters": [
{
"key": "document_type",
"value": "DL"
},
{
"key":"document_id",
"value":"432423"
},
{
"key":"payment_method",
"value":"BANK001"
}
],
"signature": "{{signature}}"
}
2.1.1.6. InitPayment Raw Response Example
HTTP/1.1 200 OK
Date: Fri, 31 Jan 2025 12:23:54 GMT
Content-Type: application/json; charset=utf-8
{
"data": {
"token": "a477435d-528d-42bc-a43d-847c2787fa41",
"status": 5,
"redirectURL": "https://{Gateway Trx
Domain}/cashier/credit-card/v1?token=a477435d-528d42bc-a43d-847c2787fa41"
},
"success": true,
"errorMessage": null,
"errorCode": 0,
"errors": {}
}
Most terminals require that transactions need to be conducted using 3D Secure technology. It means that a payment is processed asynchronously requiring the user to be redirected to a page where he enters personal data during the process. This improves security and reduces fraudulent transactions while shifting liability from merchants to the issuing banks. Visa calls this technology “Verified by Visa” and Mastercard calls it “MasterCard SecureCode”.
Transactions can fail before invoking the 3D mechanism (in case of e.g. invalid card number, expiry date, or risk checks). In this case, payment stays synchronous.
If the card is considered valid for 3D, the payment becomes asynchronous as the user gets redirected to the URL provided in response.
The merchant will be notified of the outcome via the notification URL, which should be defined by the merchant in the gateway back office.
Merchant also needs to supply the return URL where the user will be redirected to after the payment has taken place.
The asynchronous workflow should take place and look like shown in the diagram below.

For non-3D Secure transactions, the response omits redirectURL. The client receives only the transaction status:
{
"success": true,
"errorCode": 0,
"errorMessage": null,
"data": {
"token": "<transaction_token>",
"status": 1
}
}
When using asynchronous payments like 3-D secured transactions, the transaction depends on user input. Therefore, the outcome of the transaction is not available immediately after sending the request.
The gateway will send a notification to the merchant's server as soon as the payment has been completed (either approved or declined).
If the user cancels the payment (or the user doesn't complete the payment within the given time frame, e.g. 2 hours), the transaction will time out and a notification will be sent.
The notification will be sent as an HTTP POST to the notification URL specified in the gateway back office.
Notification will be pure HTTP or HTTPS-based, depending on the URL given by the merchant in the notification URL. In case it is a HTTPS-based notification, no SSL verification of the merchant SSL certificate will be performed.
Until a notification echo is rendered by the merchant, there will be up to 10 notifications sent, each with an increased time-to-time timeout. Please clarify with the Gateway integration team what IP will send the notification and whitelist it on your side.
2.4.1. Notification / Redirect Parameters
During notification or user redirection, the gateway service will send the following parameters:
Parameter | Description |
---|---|
MerchantID | Merchant long identification |
orderId | Order ID provided in initPayment request |
Status | Transaction Status |
StatusCode | Transaction status code. Merchants should make decisions according to this parameter. |
StatusMessage | Transaction request error message |
PaymentToken | Gateway ID. Save for future use (e.g., refund, transaction details lookup, etc.) |
OriginalAmount | Original transaction amount |
OriginalCurrency | Original transaction currency |
SettledAmount | Settled amount |
SettledCurrency | Settled currency |
Signature | Hashed data. To calculate the signature, see paragraph 2.4.2. |
l4d | Last 4 digits of a credit card |
ccBIN | Credit card BIN — first 6 digits |
2.4.2. Notification signature calculation
# | Parameter Name | Description |
---|---|---|
1 | paymentToken | A unique token identifies the transaction. |
2 | merchantId | The unique identifier of the merchant processing the transaction. |
3 | orderId | OrderId provided in initPayment request |
4 | transactionStatus | Transaction status |
5 | transactionErrorCode | Transaction status code. Merchants should make decision according to this parameter |
6 | transactionErrorMessage | Transaction request error message |
7 | originalAmount | Original transaction amount |
8 | settledAmount | Original transaction currency |
9 | originalCurrencyCode | Settled Amount |
10 | settledCurrencyCode | Settled Currency |
11 | secretKey | Secret key (provided by the Obtained key) |
Example of signature creation:
SHA512(<paymentToken>;<merchantId>;<orderId>;<transactionStatus>;<transactionErrorCode>;<transactionErrorMessage>;<originalAmount>;<settledAmount>;<originalCurrencyCode>;<settledCurrencyCode>;<secretKey>)
Result Should be
33e65e0a7476e3cc30132d230dfb5388083ee5450fe687921c931576e1d3e08336e6f23c3
9404a620de8b1d48133aaea624a45f6dcba6577845ad1a0452eb54b
Payout API is a REST API used to perform financial and non-financial transactions. You can use this API after authorization only by adding an Authorization Bearer header in each request.
InitPayout is the main request to the OPP system. It should be executed regardless of what payment solution (Credit Card or eWallet) you are going to use.
In general, payment behavior is configured on the terminal level by the OPP support team and there are no parameters that you can send to change the predefined flow.
According response status code, your system should decide what the next step should be. Please, see the list of all possible status codes in Appendix B.
To execute InitPayout, use a URL formatted as
<Payout API URL>/payment/initializePayout
URL Example:
https://{Gateway Trx Domain}/payment/initializePayout
Parameter Name | Required | Format | Description |
---|---|---|---|
merchantId
|
Yes |
Integer |
The unique identifier of the merchant processing the transaction. |
storeId |
Yes |
Integer | The unique identifier of the store where the transaction is initiated. |
terminalKey |
No |
String | A unique identifier assigned to a specific payment terminal for transaction processing. |
payerDetails |
Yes |
Object |
See paragraph 2.1.1.3.1. |
billingAddress |
Yes |
Object |
See paragraph 2.1.1.3.2. |
payerDevice |
Yes |
Object |
See paragraph 2.1.1.3.3. |
paymentInstrument |
No |
Object |
See paragraph 2.1.1.3.4. |
initialTransactionDetails |
Yes |
Object |
See paragraph 2.1.1.3.5. |
additionalParameters |
Yes |
Array of objects |
Extra fields are required for the specific payment method |
signature |
Yes |
String |
Hashed input data. See paragraph 2.2.4 for explanation |
{
"merchantId": 900020,
"storeId": 700010,
"terminalKey": "600513",
"payerDetails": {},
"billingAddress": {},
"payerDevice": {},
"paymentInstrument": {},
"initialTransactionDetails": [{}],
"additionalParameters": {},
"signature": "{{signature}}"
}
Parameter Name | Required | Format | Description |
---|---|---|---|
firstName | Yes | String(100) | Payer first name |
lastName | Yes | String(100) | Payer last name |
Yes | String (256) | Payer email | |
phone | Yes | String | Payer phone number with a country code, starting with the plus sign (+) |
"payerDetails": {
"firstName": "Bob",
"lastName": "Dou",
"email": "test@test.tech",
"phone": "+35799000000"
},
Parameter Name | Required | Format | Description |
---|---|---|---|
street | Yes | String (100) | Payer billing address street |
city | Yes | String(100) | Payer billing address city |
state | Yes | String (100) | Payer billing address state |
country | Yes | String (2) | Payer billing address country, ISO 2 |
zip | Yes | String (10) | Payer billing address zip code |
"billingAddress": {
"street": "Address",
"city": "City",
"state": "state",
"country": "CY",
"zip": "8541"
},
"payerDevice": {
"ip": "192.89.101.198"
},
3.1.1.3.4. Object paymentInstrument
*Required only for card transactions
Parameter Name | Required | Format | Description |
---|---|---|---|
customerAccountNumber | No | String | Card number |
customerAccountName | No | String | The cardholder's name printed on the card |
securityCode | No | String | Card CVV |
expirationMonth | No | String (2) | Card expiration month |
expirationYear | No | String (4) | Card expiration year |
"paymentInstrument": {
"customerAccountNumber": "4141000000000407",
"customerAccountName": "bob",
"securityCode": "123",
"expirationMonth": "12",
"expirationYear": "2025"
},
3.1.1.3.5. Object initialTransactionDetails
Parameter Name | Required | Format | Description |
---|---|---|---|
orderId | Yes | String (32) | Merchant unique transaction ID |
serviceName | Yes | String (100) | Free text describing the merchant’s service |
originalCurrency | Yes | String (3) | Currency of transaction, ISO 3 |
originalAmount | Yes | String (100) | The requested amount is a decimal number. |
"initialTransactionDetails": {
"orderId": "{{guid}}",
"serviceName": "Payout for something",
"originalCurrency": "EUR",
"originalAmount": "70" //1-authorized, 2-pending
},
3.1.1.3.6. Request data signature
The signature is a means of security to ensure that the merchant is the real sender of the request. It is generated by concatenating the set of parameters separated by “;” and generating a SHA512 Hash (HEX) of the string. Parameters participating in hashing are (the order of parameters is mandatory):
# | Parameter |
---|---|
1 | Merchant ID |
2 | Merchant Order ID |
3 | Request the original amount |
4 | Request original currency (upper case) |
5 | Terminal ID |
6 | Payer email |
7 | Secret key (provided by the Obtained key) |
SHA512(<merchant id>; <store id>:<order id>:<amount>:<currency>; <email>; <secret>)
Parameter Name | Format | Description |
---|---|---|
token | String | A unique token identifies the transaction. |
status | Integer | Transaction status. See Appendix B for all possible statuses. |
redirectURL | String | URL is where your system should take the end user. Use it only in case it has some value. |
success | Boolean | Indicates whether the request was successfully processed (true or false). |
errorCode | Integer | Error code. See Appendix A. |
errorMessage | String | A message describing the error (if any); null if no error. |
{
"data": {
"token": "112750b7-7a6f-4446-80bf-10297b523f11",
"status": 2,
"redirectURL": "https://{Gateway Auth
Domain}/cashier/payout/credit-card/v1?token=c517b55f-563d-450e-9c0b-2fad6de2ad32"
},
"success": true,
"errorMessage": null,
"errorCode": 0
}
3.1.1.5. InitPayout Raw Request Example
POST /payment/initializePayout HTTP/1.1
Content-Type: application/json
Host:gateway.domain.io
{
"merchantId": 904928,
"storeId": 701444,
"terminalKey": "601585",
"payerDetails": {
"firstName": "Test",
"lastName": "User",
"email": "antons@yamsoft.tech",
"phone": "+35799843239"
},
"payerDevice": {
"ip": "93.109.55.32"
},
"billingAddress": {
"address": "Address",
"city": "City",
"state": "state",
"country": "CY",
"zip": "8541"
},
"paymentInstrument": {
"customerAccountNumber": "4242424242424242",
"customerAccountName": "bob",
"securityCode": "123",
"expirationMonth": "07",
"expirationYear": "2027"
},
"initialTransactionDetails": {
"orderId": "{{guid}}",
"serviceName": "serviceName",
"originalCurrency": "EUR",
"originalAmount": "1"
},
"additionalParameters": [
{
"key": "document_type",
"value": "DL"
},
{
"key":"document_id",
"value":"432423"
},
{
"key":"payment_method",
"value":"BANK001"
}
],
"signature": "{{signature}}"
}
3.1.1.6. InitPayout Raw Response Example
HTTP/1.1 200 OK
Date: Mon, 23 Jan 2025 11:21:12 GMT
Content-Type: application/json; charset=utf-8
{
"data": {
"token": "c517b55f-563d-450e-9c0b-2fad6de2ad32",
"status": 5,
"redirectURL": "https://{Gateway Trx
Domain}/cashier/payout/credit-card/v1?token=c517b55f563d-450e-9c0b-2fad6de2ad32"
},
"success": true,
"errorMessage": null,
"errorCode": 0,
"errors": {}
}
When using asynchronous payments, the transaction depends on user input. Therefore, the outcome of the transaction is not available immediately after sending the request.
The gateway will send a notification to the merchant's server as soon as the payment has been completed (either approved or declined).
If the user cancels the payment (or the user doesn't complete the payment within the given time frame, e.g. 2 hours), the transaction will time out and a notification will be sent.
The notification will be sent as an HTTP POST to the notification URL specified in the gateway back office.
Notification will be pure HTTP or HTTPS-based, depending on the URL given by the merchant in the notification URL. In case it is a HTTPS-based notification, no SSL verification of the merchant SSL certificate will be performed.
Until a notification echo is rendered by the merchant, there will be up to 10 notifications sent, each with an increased time-to-time timeout. Please clarify with the Gateway integration team what IP will send the notification and whitelist it on your side.
3.2.1. Notification / Redirect Parameters
During notification or user redirection, the gateway service will send the next parameters:
Parameter Name | Description |
---|---|
MerchantID | Merchant long identification |
orderId | OrderId provided in initPayout request |
Status | Transaction Status |
StatusCode | Transaction status code. Merchants should make decision according to this parameter |
StatusMessage | Transaction request error message |
PayoutToken | Gateway ID. You should save it for future use (i.e refund, transaction get details, etc) |
OriginalAmount | Original transaction amount |
OriginalCurrency | Original transaction currency |
SettledAmount | Settled Amount |
SettledCurrency | Settled Currency |
Signature | Hashed data. To calculate the signature, see paragraph 2.4.2. |
l4d | Last 4 digits of a credit card. |
ccBIN | Credit Card BIN - first 6 digits |
3.2.2. Notification signature calculation
# | Parameter Name | Description |
---|---|---|
1 | paymentToken | A unique token identifies the transaction. |
2 | merchantId | The unique identifier of the merchant processing the transaction. |
3 | orderId | OrderId provided in initPayout request |
4 | transactionStatus | Transaction status |
5 | transactionErrorCode | Transaction status code. Merchants should make decision according to this parameter |
6 | transactionErrorMessage | Transaction request error message |
7 | originalAmount | Original transaction amount |
8 | SettledAmount | Original transaction currency |
9 | originalCurrencyCode | Settled Amount |
10 | settledCurrencyCode | Settled Currency |
11 | secretKey | Secret key (provided by the Obtained key) |
Example of signature creation:
SHA512(<paymentToken>;<merchantId>;<orderId>;<transactionStatus>;<transactionErrorCode>;<transactionErrorMessage>;<originalAmount>;<settledAmount>;<originalCurrencyCode>;<settledCurrencyCode>;<secretKey>)
Result Should be
33e65e0a7476e3cc30132d230dfb5388083ee5450fe687921c931576e1d3e08336e6f23c3
9404a620de8b1d48133aaea624a45f6dcba6577845ad1a0452eb54b
4.2 Dashboard Access
- URL: https://merchant.obtained.com/auth/login
- Username: Akurateco
- Password: Abc12345!
4.5 Supported Currencies & Methods
- Currencies: USD, CAD, EUR, GBP, CNY, RUB, JPY, AUD, SAR, AED, THB, TWD, SGD, IDR, INR, NZD, CHF, MYR, TRY, GHS, ZAR, PLN, HUF, NOK, BRL, CLP, MXN, ARS, VND, BOB, PHP, UGX, COP, CRC, KES, RWF, HNL, PAB, PYG, PEN, NIO, NGN, UYU, OMR, QAR, KWD
- Card Brands: VISA, Mastercard, Maestro, AMEX, Discover, Diners, JCB, UnionPay
- Recurring: No (cards) / No (checkout) – network tokenization supported
- APMs: eWallets (list provided separately)