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. 

2.1. Invoking a financial transaction

2.1.1. Deposit types

2.1.1.1. InitPayment (Sale/Auth/3D)

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. 

2.1.1.2. URL

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}}"
}
2.1.1.3.1. Object payerDetails

 

Parameter Name Required Format Description
firstName Yes String(100) Payer first name
lastName Yes String(100) Payer last name
email 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"
},

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"
},

2.1.1.3.3. Object payerDevice

 

Parameter Name Required Format Description
ip Yes String IP address of the client.

"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)
Example of signature creation:

SHA512(<merchant id>; <store id>:<order id>:<amount>:<currency>; <email>; <secret>)
2.1.1.4. Response Data
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": {}
}

2.2. 3D Secure Transactions

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.

13

2.3. Non-3D Secure Transactions

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
  }
} 

2.4. Notification for asynchronous payments

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

 

3. Payout API

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.

3.1. Invoking a financial transaction

3.1.1. Payout types

3.1.1.1. InitPayout (Sale/Auth)

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.

3.1.1.2. URL 

To execute InitPayout, use a URL formatted as

<Payout API URL>/payment/initializePayout

URL Example:
https://{Gateway Trx Domain}/payment/initializePayout

3.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": "600513",
  "payerDetails": {},
  "billingAddress": {},
  "payerDevice": {},
  "paymentInstrument": {},
  "initialTransactionDetails": [{}],
  "additionalParameters": {},
  "signature": "{{signature}}"
}
3.1.1.3.1. Object payerDetails
Parameter Name Required Format Description
firstName Yes String(100) Payer first name
lastName Yes String(100) Payer last name
email 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"
},

3.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"
},

3.1.1.3.3. Object payerDevice

 

Parameter Name Required Format Description
ip Yes String IP address of the client.

"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)
Example of signature creation:

SHA512(<merchant id>; <store id>:<order id>:<amount>:<currency>; <email>; <secret>)
3.1.1.4. Response Data 
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": {}
}

3.2. Notification for asynchronous payments

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. Technical Integration Details

4.1 Connector & Environment

 

  • Connector Name: Obtained.com
  • Acquirer System Name: Obtained
  • Supported Regions: Europe, MENA, LATAM, Asia, Canada
  • Market Segment: iGaming & FX technical gateway
  • Connector Timezone: GMT+3

4.2 Dashboard Access 

 

4.3 IP Whitelisting  

 

  • Sandbox: 62.113.214.131, 157.90.182.55, 157.90.182.5
  • Production: 62.113.196.66–69, 85.17.90.21–24 

4.4 Webhooks / Callbacks 

 

  • Available for: All transaction types
  • Sent on: Authorised, Rejected, Cancelled
  • Retry logic: Up to 10 attempts with exponential backoff until 200 OK.

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)

4.6 Integration Certification 


No separate certification files; post‑integration review performed.

What’s Next