Transaction API
Transaction API is REST API used to perform financial and non-financial transactions. You can use this API after authorization only by adding 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 URL formatted as
<Transaction 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. provided by Obtained team. You must have a store ID per used domain. |
|
payerDetails |
Yes |
Object |
See paragraph 4.1.1.3.1. |
|
billingAddress |
Yes |
Object |
See paragraph 4.1.1.3.2. |
|
payerDevice |
Yes |
Object |
See paragraph 4.1.1.3.3. |
|
paymentInstrument |
No |
Object |
See paragraph 4.1.1.3.4. |
|
initialTransactionDetails |
Yes |
Object |
See paragraph 4.1.1.3.5. |
|
signature |
Yes |
String |
Hashed input data. See paragraph 4.2.4 for
explanation |
{
"merchantId": 900020,
"storeId": 700010,
"terminalKey": "600503",
"payerDetails": {},
"billingAddress": {},
"payerDevice": {},
"paymentInstrument": {},
"initialTransactionDetails": {},
"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 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": "",
"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):
| 1 | Merchant ID |
|---|---|
| 2 | Merchant Order ID |
| 3 | Request original amount |
| 4 | Request original currency (upper case) |
| 5 | Terminal ID |
| 6 | Payer email |
| 7 | Secret key (provided by Obtained key) |
SHA512(<merchant id>; <order id>:<binn>:<last4>:<amount>; <currency>; <key>; <email>; <fname>;<lname>; <secret>)SHA512 (XXX000652;ORDER11:411111;1111; 1000; USD;sdf76sdf;T@TEST.com; SERGIO:GARCIA;sk)
Result should be
48E2CC20F44C35877828770659A3D65E705BC0D35E06E5947D8EA581F73CD1C698CFBC5B0DBC5E65BC8942DBDE2535CEA7CBD860D7DA0FCEAC256A8CB4D0C272
| Parameter Name | Format | Description |
|---|---|---|
| token | String | A unique token identifies the transaction. |
| status | Integer | Transaction status. See Appendix B for all possible statuses.l |
| 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/Response Example
POST /payment/initializePayment HTTP/1.1
Content-Type: application/json
Host: stage-gateway.domain.io
{
"merchantId": 900020,
"storeId": 700010,
"payerDetails": {
"firstName": "Bob",
"lastName": "Dou",
"email": "test@test.tech",
"phone": "+35799000000"
},
"payerDevice": {
"ip": "192.109.55.32"
},
"billingAddress": {
"street": "Address",
"city": "City",
"state": "state",
"country": "CY",
"zip": "8541"
},
"paymentInstrument": {
"customerAccountNumber": "4000000000000407",
"customerAccountName": "bob"
"securityCode": "123",
"expirationMonth": "12",
"expirationYear": "2025"
},
"initialTransactionDetails": {
"orderId": "sao_postman_357101ff-50af-4219-a94a-d5b118f85828",
"serviceName": "serviceName",
"originalCurrency": "EUR",
"originalAmount": "77"
},
signature":
"634b2f560468f4140606c29495a35a00ab425e97a5e1caae43197cb78b9339fe8683e46e4395b708fd3f7a907de85d558a3098d130e175bb5d9435d0c82cb0eb"
}
HTTP/1.1 200 OK
Date: Fri, 31 Jan 2025 12:23:54 GMT
Content-Type: application/json; charset=utf-8
{"data":{"token":"dd537dfb-0481-4cae-9c74-3eaeb47b8a23","status":2,"redirectURL":"https://stage-merchant.dom
ain.io/cashier/product/v1?token=dd537dfb-0481-4cae-9c74-3eaeb47b8a23"},"success":true,"errorMessage":null,"e
rrorCode":0}
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”. The asynchronous workflow should take place and look like shown in the diagram below:
Transactions can fail prior to 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.
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.3.1. Notification / Redirect Parameters
| MerchantID | Merchant long identification |
|---|---|
| OrderNumber | OrderId provided in initPayment request |
| Status | Transaction Status |
| StatusCode | Transaction status code. Merchants should make decision according to this parameter |
| StatusMessage | Transaction request error message |
| PaymentToken | 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 4.3.2. |
| l4d | Last 4 digits of a credit card. |
| ccBin | Credit Card BIN - first 6 digits |
SHA512 (<MerchantId>; <OrderId>; <OriginalAmount>; <SettledAaount>; <OriginalCurrency>; <Set tledCurrency>; <StatusCode>; <Gateway TransactionId>; <EcoParam>; <secret>)
SHA512 (XXX000123; ORDERID123; 1000; 1000; USD; USD; 0;123;ecapam12230;sk)
Result should be
33e65e0a7476e3cc30132d230dfb5388083ee5450fe687921c931576e1d3e08336e6f23c3
9404a620de8b1d48133aaea624a45f6dcba6577845ad1a0452eb54b