OdeonPay API
OdeonPay payment gateway integration API documentation
Terms and Definitions
System — OdeonPay payment gateway.
Merchant — OdeonPay client who works with the System.
API — application program interface for interacting with the system, located at https://api.odeonpay.com
Back Office — merchant's back office in the system, located at https://merchant.odeonpay.com
Card — a bank card of Visa, MasterCard or MIR systems.
Acquirer — a settlement bank.
Issuer — a bank that issued a card.
Cardholder — an owner of a card issued by a bank.
Widget — payment form, provided by the system to enter card data by a holder and perform a further authorization.
3-D Secure — protocol to verify a holder by the issuer.
Transaction types
The system involves three types of operations: payment, refund, and payout. In the first case, money is transferred from holder's account to the merchant, in the second - vice versa. A merchant performs a refund if a buyer wants to return goods, and it is always associated with a payment transaction, which amount returns to a holder. It is possible to refund a whole payment amount or it's part only. Money usually comes back to a holder’s card the same day, but sometimes (it depends on an issuer) it can take up to 3 days. Payout operation is used to transfer the funds from the merchant account to the Cardholder's account. The payout is possible only when the initial payment with a Card was done using the System.
Payment Methods
Via payment form — widget. Add a script that opens a secure payment form (iframe) to enter card data.
Via API by a card’s cryptogram. Add a checkout to your web site which collects card data from any web site’s form, encrypts and creates a cryptogram for a secured transmission through an interserver interaction.
Via redirect. User gets redirect to a payment page hosted on our servers.
3-D Secure
3-D Secure is a common name of Verified By Visa and MasterCard Secure Code programs from Visa and MasterCard's respectively. In general, such program shall authenticate a cardholder (that is to protect against an unauthorized card usage) by an issuer before a payment. Actually, it looks as follows: a cardholder specifies card data. Then the issuer’s web site opens, where a cardholder has to enter a password or a secret code (usually, the code is sent in a SMS message). If the code is correct, a payment will be successful. Otherwise, it will be rejected.
During the payment process, 3-D Secure appears not on all cards, but only on those, Issuers supporting this technology. Certainly, payments without 3-D Secure are a less secure option.
Payment via Redirect
In Payment Redirect method the user gets redirected to the payment page, hosted by the System. After the user has entered his/her bank card data, the user then gets redirected back to the merchant site.
The Payment Redirect link is located in the Back Office and can be used in the following way:
https://api.odeonpay.com/payments/redirect/pbid_2kajhh9oqhmpwjqgd529rg?
\ amount=10.50&
\ description=Payment&
\ currency=EUR&
\ invoiceId=0001&
\ accountId=account%40example.com&
\ successUrl=https%3A%2F%2Fwww.example.com%2Fsuccess&
\ failureUrl=https%3A%2F%2Fwww.example.com%2Ffailure&
\ pendingUrl=https%3A%2F%2Fwww.example.com%2Fpending&
\ cancelUrl=https%3A%2F%2Fwww.example.com%2Fcancel&
\ locale=en_USParameter
Type
Usage
Description
amount
Number
Required
Payment amount
description
String
Required
Description of a payment purpose in text format
currency
String
Required
Payment currency
invoiceId
String
Optional
Order or Invoice number
accountId
String
Optional
Payer's identifier. If specified, the payment token will be returned in the Notification which can be used for payouts
successUrl
String
Required
URL the user gets redirected, after the successful charge transaction.
failureUrl
String
Required
URL the user gets redirected, after the charge transaction has failed.
pendingUrl
String
Required
URL the user gets redirected when the charge transaction status cannot be immediately returned. The merchant should expect to receive the end status of the transaction in Notification.
cancelUrl
String
Required
URL the user gets redirected, after the payment was cancelled by the user.
locale
String
Optional
Payment form language. The default language is English when the parameter is not specified.
Payment Widget
Payment widget is a pop-up form to enter card data and payer’s email address. The widget automatically defines a payment system type: Visa, MasterCard, Maestro or MIR, and an emitting bank of a card and corresponding logos. The form is optimized for use in any browsers and mobile devices. There is an iframe opens within a widget which guarantees a security of card data sending and does not require a certification for merchant's usage.
Widget Installation
To install a widget, you need to add a script on a web site to the head section:
<script src="https://widgetui.odeonpay.com/assets/js/payment.js"></script>Define a function for charge method calling for payment form to display
var odeonPay = new OdeonPay();
pay = function () {
odeonPay.charge({
publicId: 'pbid_2kajhh9oqhmpwjqgd529rg', //id of site (see your merchant account page)
amount: 68.54,
currency: 'EUR',
invoiceId: '9264', // order number (optional)
description: 'Product purchasing example',
accountId: '[email protected]' // payer identification (optional)
},
function (options) {
// after payment success
console.log('payment success');
},
function (reason, options) {
// after payment failure
console.log('payment failed');
});
return odeonPay;
};Call the function when some event is emitted, for example click on the «Pay» button:
$('#checkout').click(pay);Or use a link to call the payment method:
<a href="javascript:" onclick="pay()">Pay</a><br/>Parameters
Parameter
Type
Usage
Description
publicId
String
Required
A merchant identifier, located in Back Office
description
String
Required
Description of a payment purpose in text format
amount
Numeric
Required
Payment amount
currency
String
Required
Payment currency
invoiceId
String
Optional
Order or Invoice number
accountId
String
Optional
Payer's identifier. If specified, the payment token will be returned which can be used for payouts
locale
String
Optional
Payment widget's language. The default language is English when the parameter is not specified.
You can define the form behaviour for successful or unsuccessful payment using the following parameters:
Parameter
Type
Usage
Description
onSuccess
Function
Optional
Function will be called after successful payment completion
onFail
Function
Optional
Function will be called after unsuccessful payment completion
Locale
You can specify you language locale when the payment widget is created. The following locales are supported right now:
Locale
Language
en_US
English language. Used by default.
ru_RU
Russian
API
API is an application program interface to interact with Merchant's system.
Interface works on api.odeonpay.com and provides functionality for making a payment, refunding, and payouts.
Parameters are sent by POST method in a request body in JSON format. Use application/json Content-Type for data transfer.
The system returns a response in JSON format which includes at least two parameters: success and message:
{ "Success": false, "Message": "Invalid Amount value" }Requests Authentication
For authentication HTTP Basic Auth is used which is sending a login and a password in a header of HTTP request. Public ID serves as a login and API Secret serves as a password. Both of these values you can get in the back office.
If a request does not contain a header with authentication data, or incorrect data is sent, the system returns 401 HTTP status - Unauthorized.
Duplicate Requests Protection
invoiceId parameter is used to identify the uniqueness of the request sent from the Merchant to the System. That means you can send several requests to the system with the same invoiceId identifier, and only one request will be processed. The following requests with the same invoiceId will be Declined. Thus the protection against network errors is implemented which can lead to creation of duplicate records and actions. The time interval when the System considers the received invoiceId is duplicate can be configured individually per Merchant.
Test
POST https://api.odeonpay.com/test
The method to test the interaction with the API.
Headers
Authorization
string
HTTP Basic authentication
Content-Type
string
application/json
{"success": true, "message": "Test message success"}Payment
POST https://api.odeonpay.com/payments/charge/card
The method to request a payment with Card data supplied. This method is used when the Card data is collected on the merchant's side.
Headers
Authorization*
string
HTTP Basic authentication
Content-Type*
string
application/json
Request Body
publicId*
string
Merchant identifier. Located in the Back Office
amount*
number
Payment amount
currency*
string
Payment currency
name*
string
Cardholder's name
description*
string
Description
card*
object
Card data of a payment. See the example below for the card data object structure.
invoiceId
string
Order or invoice number
accountId*
string
Payer's e-mail address. If specified, the payment token will be returned which can be used for Payouts
ip*
string
Payer's IP address
successRedirectUrl
string
URL the user gets redirected to after the successful charge transaction. This parameter is used only when the integration supports "Redirect 3-DS" schema.
failureRedirectUrl
string
URL the user gets redirected to after the charge transaction has failed. This parameter is used only when the integration supports "Redirect 3-DS" schema.
pendingRedirectUrl
string
URL the user gets redirected to when the end status of the transaction cannot be retrieved yet. This parameter is used only when the integration supports "Redirect 3-DS" schema.
{
"success": true,
"message": null,
"model": {
"transactionId": 524,
"amount": 40.11,
"currency": "EUR",
"invoiceId": "9276334",
"accountId": "[email protected]",
"description": "Payment for products",
"name": "John Doe",
"token": "8163-KS17-JV29-KF28",
"statusCode": 4,
"status": "Completed",
"reasonCode": 0,
"reason": "Approved"
}
}Payment request example
{
"publicId": "pbid_2kajhh9oqhmpwjqgd529rg",
"amount": 40.11,
"currency": "EUR",
"name": "John Doe",
"invoiceId": "927829",
"description": "Payment for products",
"accountId": "[email protected]",
"card": {
"publicId": "pbid_2kajhh9oqhmpwjqgd529rg",
"pan": "4242424242424242",
"cvv": "123",
"expiryMonth": 12,
"expiryYear": 2023
},
"browserData": {
"colorDepth": "24",
"javaEnabled": "false",
"screenHeight": "600",
"screenWidth": "800",
"language": "en_US",
"acceptHeader": "text/html,application/xhtml+xml,application/xml",
"timeZoneOffset": "+120",
"userAgent": "AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0"
},
"data": {
"countryCode": "UK",
"city": "London",
"address": "Wall Street 15",
"postcode": "12384",
"phone": "441632960909",
"state": "",
"birthDate": "1980-04-25",
"firstName": "John",
"lastName": "Doe"
}
}Response: transaction success
{
"success": true,
"message": null,
"model": {
"transactionId": 524,
"amount": 40.11,
"currency": "EUR",
"invoiceId": "9276334",
"accountId": "[email protected]",
"description": "Payment for products",
"name": "John Doe",
"token": "8163-KS17-JV29-KF28",
"statusCode": 4,
"status": "Completed",
"reasonCode": 0,
"reason": "Approved"
}
}Response: transaction failure
{
"success": false,
"message": "Insufficient funds to process the transaction",
"model": {
"transactionId": 524,
"amount": 2873.00,
"currency": "EUR",
"invoiceId": "9276334",
"accountId": "[email protected]",
"description": "Payment",
"name": "John Doe",
"token": null,
"statusCode": 99,
"status": "Declined",
"reasonCode": 5051,
"reason": "Insufficient Funds"
}
}Response: 3-D Secure authentication redirect is required (Redirect 3-DS)
Payment response depends on the processing card. If the card participates in 3-D Secure, in Redirect 3-DS schema the response will contain a link, the user should be redirected to, to complete the 3-D Secure authentication.
{
"success": false,
"message": "Requires 3DS authentication",
"threeDsRedirectModel": {
"url": "https://api.odeonpay.com/redirect/?link_reference=437b2e80220a11bc8b532f4e2aa8c471",
"transactionId": 525,
"statusCode": 1,
"status": "AwaitingAuthentication"
}
}After completing the 3-D Secure verification, depending on the verification results, the user gets redirected either to successRedirectUrl or failureRedirectUrl or pendingRedirectUrl parameter value, supplied in the Payment request.
Response: 3-D Secure authentication handling by merchant is required (Advanced 3-DS)
{
"success": false,
"message": "Requires 3DS authentication",
"threeDsModel": {
"transactionId": 529,
"method": "post",
"paReq": "eNpdU8tymzAU3ecrvMumYz1AgD2yZnDsTpMZx06TRdudLK5skhiIgNjust/Tr+qXVMIm4DDDoHvuOdKZexB/2hqA2SOo2oC4Ggz4AspSbmCQJpPrSELAZKApSOyFkWYaY+brJAq0pzTQa6ewmlX8Hd4aRZDoKMIs8WXiK2/NvIAFDPwwoRrCkV6fFVbzDqZM80yQIR5SjtqybRcyE4xFPmUhoZiGhPkRRw5tGQswaiuzqgUsJNXb9PZeMBpYFUfnsuvvwNzOBKa4fTg6QR0lkzsQ84PcFa/AUVN1TZXXWWWOgmLrpS26dm1exbaqijFC+/1+CKddhrnZII5cs7WOPnvnq9oBZf+wQ5qIxSzed+/8uPj9QO6flb98iiccOUbHT2QF1hlhmODRgARj6o0Z46jBezPaOd/i35+/hH7x7ATOQMconJf4hBLqKH2kN43aGMjUUYxCN4626ghwKPIMrMbm+7HuGYZSCevPfT4m83kQ/ObbRcCqsnHls7V++fVAHoPlnb/9eVMuVz+m8fzrNN5MXOwN6cJHaoMiETkZSbvUOGr3t0e7v7i5A+h8CcQVR5cX5D/FxN2u",
"acsUrl": "http://ascbank.redisecure.com/ascpage/cap?id=8276844",
"statusCode": 1,
"status": "AwaitingAuthentication"
}
}In the Advanced 3-DS schema, to complete 3-D Secure authentication, merchant needs to forward a payer to the address specified in the acsUrl parameter of the server's response with following parameters:
MD — transactionId parameter from server response
PaReq — same parameter from server response
TermUrl — the address on your site for returning the payer once authentication successful
Form example
<form name="paymentForm" action="AcsUrl" method="POST">
<input type="hidden" name="PaReq" value="eNpdU8tymzAU3ecrvMumYz1AgD2yZnDsTpMZx06TRdudLK5skhiIgNjust/Tr+qXVMIm4DDDoHvuOdKZexB/2hqA2SOo2oC4Ggz4AspSbmCQJpPrSELAZKApSOyFkWYaY+brJAq0pzTQa6ewmlX8Hd4aRZDoKMIs8WXiK2/NvIAFDPwwoRrCkV6fFVbzDqZM80yQIR5SjtqybRcyE4xFPmUhoZiGhPkRRw5tGQswaiuzqgUsJNXb9PZeMBpYFUfnsuvvwNzOBKa4fTg6QR0lkzsQ84PcFa/AUVN1TZXXWWWOgmLrpS26dm1exbaqijFC+/1+CKddhrnZII5cs7WOPnvnq9oBZf+wQ5qIxSzed+/8uPj9QO6flb98iiccOUbHT2QF1hlhmODRgARj6o0Z46jBezPaOd/i35+/hH7x7ATOQMconJf4hBLqKH2kN43aGMjUUYxCN4626ghwKPIMrMbm+7HuGYZSCevPfT4m83kQ/ObbRcCqsnHls7V++fVAHoPlnb/9eVMuVz+m8fzrNN5MXOwN6cJHaoMiETkZSbvUOGr3t0e7v7i5A+h8CcQVR5cX5D/FxN2u">
<input type="hidden" name="MD" value="529">
<input type="hidden" name="TermUrl" value="https://merchant.example.com/post3ds?orderId=82794">
</form>
<script>
window.onload = submitForm;
function submitForm() { paymentForm.submit(); }
</script>To complete the payment, use post3ds method.
Please contact your Account Manager to clarify if Advanced 3-DS schema is available for your integration.
Post 3-D Secure
POST https://api.odeonpay.com/payments/post3ds
The method to validate payment's 3-D Secure authentication
Headers
Authorization*
string
HTTP Basic authentication
Content-Type*
string
application/json
Request Body
transactionId*
integer
MD parameter value
paRes*
string
Received PaRes value
{
"success": true,
"message": null,
"model": {
"transactionId": 524,
"amount": 40.11,
"currency": "EUR",
"invoiceId": "9276334",
"accountId": "[email protected]",
"description": "Payment for products",
"name": "John Doe",
"token": "8163-KS17-JV29-KF28",
"statusCode": 4,
"status": "Completed",
"reasonCode": 0,
"reason": "Approved"
}
}The server will return either information about successful transaction or declined in response to correctly created request.
Refund
POST https://api.odeonpay.com/payments/refund
The method to return the funds of a successfully completed charge operation
Headers
Authorization*
string
HTTP Basic authentication
Content-Type*
string
application/json
Request Body
transactionId*
integer
Transaction ID of successfully completed charge transaction
amount
number
Refund amount. If the amount is not provided, the transaction is refunded in full of the initial charge amount. The transaction can be refunded partially as well.
{
"model": {
"transactionId": 1039
},
"success": true,
"message": null
}Request example
{
"transactionId": 524,
"amount": 13.34
}Payout via token
POST https://api.odeonpay.com/payments/payout
The method to payout the funds to a Card by provided token
Headers
Authorization*
string
HTTP Basic authentication
Content-Type*
string
application/json
Request Body
token*
string
Token of the card. The token is received in response message after the successful Payment API method call.
amount*
number
Payout amount
accountId*
string
Payer's e-mail address.
currency*
string
Payout currency
invoiceId
string
Order or invoice number
{
"success": true,
"message": null,
"model": {
"transactionId": 2533,
"amount": 12.30,
"currency": "EUR",
"invoiceId": null,
"accountId": "[email protected]",
"name": "John Doe",
"statusCode": 7,
"status": "PayoutCompleted",
"reasonCode": 0,
"reason": "Approved"
}
}Request example
{
"token": "8163-KS17-JV29-KF28",
"amount": 12.30,
"accountId": "[email protected]",
"currency": "EUR"
}Payout to card
POST https://api.odeonpay.com/payments/payout/card
Payout method when the funds are transferred to the provided credit card
Headers
Authorization*
string
HTTP Basic authentication
Content-Type*
string
application/json
Request Body
pan*
string
Card number
name*
string
Cardholder name
amount*
number
Payout amount
currency*
string
Payout currency
invoiceId
string
Order or invoice number
data
string
Payout recipient additional data
{
"success": true,
"message": null,
"model": {
"transactionId": 2533,
"amount": 12.30,
"currency": "EUR",
"invoiceId": "11928485",
"accountId": null,
"name": "John Doe",
"statusCode": 7,
"status": "PayoutCompleted",
"reasonCode": 0,
"reason": "Approved"
}
}Request example
{
"pan": "4242424242424242",
"name": "John Doe",
"amount": 12.30,
"currency": "EUR",
"invoiceId": "11928485",
"data": {
"phone": "+999389235",
"address": "Wall street 65",
"city": "New York",
"countryCode": "US",
"birthDate": "1980-11-25"
}
}Status
POST https://api.odeonpay.com/payments/status
Returns the current status of the requested transaction.
Headers
Authorization*
string
HTTP Basic authentication
Content-Type*
string
application/json
Request Body
transactionId*
string
Transaction ID to check the status of
{
"model": {
"transactionId": 144221,
"amount": 12.30,
"currency": "EUR",
"invoiceId": "11928485",
"accountId": "[email protected]",
"name": "John Doe",
"statusCode": 4,
"status": "Completed",
"reasonCode": 0,
"reason": "Approved",
"operationTypeCode": 1,
"operationType": "Payment"
},
"success": true,
"message": null
}Request example
{
"transactionId": 144221
}Status Invoice
POST https://api.odeonpay.com/payments/status/invoice
Returns the current status of the requested transaction.
Headers
Authorization*
string
HTTP Basic authentication
Content-Type*
string
application/json
Request Body
invoiceId*
string
Transaction Invoice ID to check the status of
{
"success": true,
"message": null,
"transactions": [
{
"transactionId": 501166,
"amount": 2.54,
"currency": "EUR",
"invoiceId": "1781",
"accountId": "[email protected]",
"name": "John Deer",
"statusCode": 4,
"status": "Completed",
"reasonCode": 0,
"reason": "Approved",
"operationTypeCode": 1,
"operationType": "Payment"
},
{
"transactionId": 501167,
"amount": 2.54,
"currency": "EUR",
"invoiceId": "1781",
"accountId": "[email protected]",
"name": "John Deer",
"statusCode": 99,
"status": "Declined",
"reasonCode": 6002,
"reason": "Duplicate invoice ID",
"operationTypeCode": 1,
"operationType": "Payment"
}
]
}Request example
{
"invoiceId": "1781"
}Checkout
POST https://api.odeonpay.com/checkout/link
Allows merchants to dynamically generate a checkout link for processing card payments. Merchants can customize the appearance of the payment form by passing various styling parameters.
Headers
Authorization*
string
HTTP Basic authentication
Content-Type*
string
application/json
Request Body
amount
number
The payment amount.
currency
string
The currency of the payment (e.g., USD, EUR).
description
string
A description of the transaction.
invoiceId
string
Unique identifier for the invoice.
accountId
string
The merchant's account identifier (e.g., email).
successUrl
string
The URL to redirect the customer upon successful payment.
failureUrl
string
The URL to redirect the customer upon failed payment.
pendingUrl
string
The URL to redirect the customer when payment is pending.
cancelUrl
string
The URL to redirect the customer when payment is canceled.
locale
string
The locale setting (e.g., en_US, fr_FR).
ip
string
The IP address of the customer.
data
object
Optional user information
page
object
Optional customization for Payment Form
Object 'data' (Optional user information)
personId
string
The unique identifier of the person.
firstName
string
The customer's first name.
lastName
string
The customer's last name.
countryCode
string
The country code of the customer.
state
string
The state of the customer.
city
string
The city of the customer.
address
string
The address of the customer.
postcode
string
The postal code of the customer.
phone
string
The phone number of the customer.
Object 'page' (Optional customization for Payment Form)
logo
string
The logo identifier for the merchant.
leftContainerBackgroundColor
string
Background color for the left section (e.g., #172650).
merchantTitle
string
The title of the merchant displayed on the payment page.
priceHeadingColor
string
Color of the price heading.
backLinkColor
string
Color of the back link.
backLinkHoverColor
string
Hover color of the back link.
bodyFont
string
The font used for the body text.
payButtonColor
string
Background color of the pay button.
payButtonTextColor
string
Text color of the pay button.
payButtonWithPrice
boolean
Whether the price is displayed on the pay button.
rightContainerBackgroundColor
string
Background color for the right section.
rightContainerHeadingColor
string
Heading color for the right section.
formLabelColor
string
Color of form labels.
formErrorColor
string
Color of form error messages.
formControlBorderColor
string
Border color of input fields.
formControlBorderRadius
string
Border radius for input fields.
footerColor
string
Color of the footer text.
footerIcons
array
List of icons displayed in the footer (e.g., secure-connection, verified-by-visa).
footerText
string
The text displayed in the footer.
fields
array
List of additional fields to display (email, phone, shipping_address, billing_address).
{
"success": true,
"message": null,
"model": {},
"link": {
"method": "get",
"action": "https://api.odeonpay.com/aaa-bbb-ccc-123"
}
}Checkout request example:
{
"amount": 10.66,
"currency": "USD",
"description": "Payment for products",
"invoiceId": "990022",
"accountId": "[email protected]",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/failure",
"pendingUrl": "https://example.com/pending",
"cancelUrl": "https://example.com/cancel",
"locale": "en_US",
"ip": "10.20.30.40",
"data": {
"firstName": "John",
"lastName": "Doe"
},
"page": {
"logo": "merchant-logo",
"leftContainerBackgroundColor": "#172650",
"merchantTitle": "Merchant #1",
"priceHeadingColor": "#fff",
"backLinkColor": "#5D6784",
"backLinkHoverColor": "#fff",
"bodyFont": "BlinkMacSystemFont, Segoe UI, Roboto, Helvetica Neue, Ubuntu, sans-serif",
"payButtonColor": "#172650",
"payButtonTextColor": "#9b8a8a",
"payButtonWithPrice": true,
"rightContainerBackgroundColor": "#fff",
"rightContainerHeadingColor": "#2E2522",
"formLabelColor": "#514643",
"formErrorColor": "#DC2F2E",
"formControlBorderColor": "#e0e0e0",
"formControlBorderRadius": "6px",
"footerColor": "#A2A8B9",
"footerIcons": [
"secure-connection",
"verified-by-visa",
"mastercard-secure-code",
"mir-accept",
"american-express",
"pci-dss"
],
"footerText": "This is footer text that is displayed",
"fields": [
"email",
"phone",
"shipping_address",
"billing_address"
]
}
}List
POST https://api.odeonpay.com/payments/list
Returns the lists of all transactions for a day.
Headers
Authorization*
string
HTTP Basic authentication
Content-Type*
string
application/json
Request Body
date*
string
Date when transactions were created in 'YYYY-MM-DD' format.
timezone
string
Transactions date timezone. See Timezones dictionary for available timezones. If timezone is not specified, the transactions are returned based on UTC.
{
"success": true,
"message": null,
"transactions": [
{
"id": 16213,
"statusId": 4,
"status": "Completed",
"currency": "USD",
"amount": 65.77,
"description": "Products Payment",
"invoiceId": "132-33541-34",
"accountId": "[email protected]",
"created": 1606726879000,
"operationTypeId": 1,
"operationType": "Payment",
"reasonId": 0,
"reason": "Approved",
"cardType": "Visa",
"cardFirstSix": "411111",
"cardLastFour": "1111",
"completed": 1606726905000,
"paymentTransactionId": null
}
]
}Request example
{"date":"2020-10-25", "timezone":"Europe/Moscow"}Link
POST https://api.odeonpay.com/payments/link
The method is used to generate a payment link, where the user can be redirected to proceed with the payment. When the payment is requested, a payment link is generated and returned in the "link" field of the response or the merchant can use returned parameters to render their own payment form (Host-2-Host integration).
Headers
Authorization*
string
HTTP Basic authentication
Content-Type*
string
application/json
Request Body
amount*
number
Payment amount
currency*
string
Payment currency
description*
string
Payment description in text format
invoiceId
string
Order or invoice number
accountId*
string
Payer's identifier
successUrl
string
The URL address the user gets redirected after successful payment operation
failureUrl
string
The URL address the user gets redirected after the payment transaction has failed
pendingUrl
string
The URL address the user gets redirected when the payment processing is pending
cancelUrl
string
The URL address the user gets redirected when the payment has been cancelled by the user
locale
string
Payment form language. English language is used by default when no locale specified
ip*
string
IP address of the payer.
data
object
Additional data required for the payment processing. See request example for available fields in the data object.
Successful Response (200)
The API returns a link object that can be used in two ways:
Redirect — use the provided
actionURL to redirect the user to hosted payment page.H2H Integration — use parameters returned in
link.paramsto render your own payment interface.
Standard Redirect Example
{
"success": true,
"message": null,
"model": {
"transactionId": 356244,
"amount": 10.66,
"currency": "USD",
"invoiceId": "990022",
"accountId": "[email protected]",
"description": "Payment for products",
"statusCode": 10,
"status": "Created",
"reasonCode": 0,
"reason": "Approved"
},
"link": {
"method": "get",
"action": "https://checkout.odeonpay.com/?f8927-3928f-2398-3939"
}
}H2H Integration Examples
In some cases, instead of a single redirect URL, the link.params field may contain specific values allowing the merchant to render their own payment UI.
1. QR Code Payment
If a QR code is available for payment (e.g. for QRIS or similar), it is returned in the qr parameter.
"link": {
"method": "GET",
"action": "https://api.odeonpay.com/payments/redirect-content/...",
"params": {
"qr": "00020101021226670016COM.NOBUBANK.WWW01..."
}
}
Usage: Render the QR code string into an image using a QR code generator on your side.
2. UPI Intent Link (India)
For UPI payments (e.g. paymentTypeId = 2000), an intent URI may be returned.
"link": {
"method": "GET",
"action": "https://api.odeonpay.com/payments/redirect-content/...",
"params": {
"intent": "upi://pay?pa=9258493441m@pnb&pn=9258493441m@pnb&cu=INR"
}
}
Usage: Open the UPI intent link in the mobile app or browser that supports UPI.
3. Bank Transfer Details
If the payment requires a manual bank transfer, the following banking details will be returned:
"link": {
"method": "GET",
"action": "https://api.odeonpay.com/payments/redirect-content/...",
"params": {
"bankName": "Bank",
"bankAccountHolder": "John Doe",
"bankAccountNumber": "1234567890"
}
}
Usage: Show these fields in your interface to instruct the customer to transfer the funds manually.
Important Notes:
In all cases, the
link.actionfield is still provided. Merchants who prefer not to build their own UI can always redirect the user to this URL for a ready-to-use hosted payment page.If
link.paramsis present, you are free to use these values for a customised user experience.
Request example
{
"amount": 10.66,
"currency": "USD",
"description": "Payment for products",
"invoiceId": "990022",
"accountId": "[email protected]",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/failure",
"pendingUrl": "https://example.com/pending",
"cancelUrl": "https://example.com/cancel",
"locale": "en_US",
"ip": "10.20.30.40",
"data": {
"personId": "4000878749933",
"phone": "+73838247553",
"address": "Wall Street 14-49",
"city": "New York",
"firstName": "John",
"lastName": "Doe",
"countryCode": "BR",
"paymentTypeId": 1000
}
}Balance
GET https://api.odeonpay.com/payments/balance
Returns the list of available accounts and balance. The balance is calculated taking into account the amount of successful payments, payouts, holds and fees.
Headers
Authorization*
string
HTTP Basic authentication
Content-Type*
string
application/json
{
"success": true,
"message": null,
"balances": [
{
"name": "The balance",
"currencies": [
{
"currency": "EUR",
"total": 14633.00,
"pending": 0.00,
"hold": 481.70,
"fee": 529.98,
"pendingFee": 0.00,
"available": 13621.32
},
{
"currency": "USD",
"total": 59483.00,
"pending": 503.00,
"hold": 3220.70,
"fee": 1003.98,
"pendingFee": 45.10,
"available": 54710.22
},
]
}
]
}Response fields description
Parameter
Type
Description
currency
String
Balance currency
total
Number
Total funds amount on the balance
pending
Number
Funds that are reserved for ongoing transactions
hold
Number
Funds on hold
fee
Number
Acquiring and other fees
pendingFee
Number
Funds that are reserved for ongoing fees
available
Number
Funds available for operations
Alternative Payment Methods
Alternative Payments Methods (APM) include non-card transactions. Good examples of Alternative Payments Methods are banklinks, kiosks, e-wallets, etc. See the list of available APMs below.
Method
Type ID
Method
Country
Request example
APM Test Payment
1
Link
APM Test Payout
2
APM Payout
YooMoney (Yandex Money)
201
Link
Russia
WebMoney
501
Link
Russia
Banco Itau
1000
Link
Brazil
Santander Brasil
1001
Link
Brazil
Banco do Brasil
1002
Link
Brazil
Banrisul
1003
Link
Brazil
Bradesco Pague Facil
1004
Link
Brazil
Bradesco Pague Facil
1005
Link
Brazil
Caixa Econômica Federal
1006
Link
Brazil
Banco Itau Boleto
1007
Link
Brazil
UPI
2000
Link
India
Google Pay
2001
Link
India
JioMoney
2002
Link
India
Airtel Money Wallet
2003
Link
India
Reliance Jio Wallet
2004
Link
India
Freecharge Wallet
2005
Link
India
Phonepe Wallet
2006
Link
India
Amazon Wallet
2007
Link
India
Ola Money Wallet
2008
Link
India
Mobikwik Wallet
2009
Link
India
Bank Of Maharashtra
2010
Link
India
Central Bank Of India
2011
Link
India
Hdfc Bank
2012
Link
India
Canara Bank
2013
Link
India
Bank Of India
2014
Link
India
City Union Bank
2015
Link
India
Federal Bank
2016
Link
India
Icici Bank
2017
Link
India
Indian Bank
2018
Link
India
Indian Overseas Bank
2019
Link
India
Industrial Development Bank Of India
2020
Link
India
Indusind Bank
2021
Link
India
Jammu And Kashmir Bank
2022
Link
India
Karnataka Bank Ltd
2023
Link
India
Karur Vysya Bank
2024
Link
India
State Bank Of India
2025
Link
India
South Indian Bank
2026
Link
India
Kotak Bank
2027
Link
India
Union Bank Of India
2028
Link
India
Bank Of Baroda Retail Accounts
2029
Link
India
Yes Bank
2030
Link
India
Andhra Bank
2031
Link
India
Uco Bank
2032
Link
India
Catholic Syrian Bank
2033
Link
India
Allahabad Bank
2034
Link
India
Dhanalaxmi Bank Corporate
2035
Link
India
Laxmi Vilas Bank - Corporate Net Banking
2036
Link
India
Punjab National Bank
2037
Link
India
Standard Chartered Bank
2038
Link
India
Punjab And Sind Bank
2039
Link
India
Saraswat Cooperative Bank
2040
Link
India
VISA/MC/RuPay
2041
Link
Worldwide
Paytm, IN, Online
2042
Link
India
IDFC BANK
2053
Link / APM Payout
India
India Bank Selection
2060
Link
India
UPI QR
2080
Link
India
Axis Bank
2081
Link / APM Payout
India
Bandhan Bank
2082
Link / APM Payout
India
Bank Of Baroda
2083
Link / APM Payout
India
Federal Bank LTD
2084
Link / APM Payout
India
IDBI Bank
2085
Link / APM Payout
India
India Post Payment Bank
2086
Link / APM Payout
India
Jammu and Kashmir Bank Limited
2087
Link / APM Payout
India
Karnataka Bank Limited
2088
Link / APM Payout
India
Lakshmi Vilas Bank
2090
Link / APM Payout
India
PAYTM Payments Bank LTD
2091
Link / APM Payout
India
Ujjivan Small Finance Bank
2092
Link / APM Payout
India
UPI Payouts
3020
APM Payout
India
Bank Transfer Payouts
3021
APM Payout
India
Techcombank
7000
Link / APM Payout
Vietnam
Sacombank
7001
Link / APM Payout
Vietnam
Vietcombank
7002
Link / APM Payout
Vietnam
Asia Commercial Bank
7003
Link / APM Payout
Vietnam
DongA Bank
7004
Link / APM Payout
Vietnam
Vietinbank
7005
Link / APM Payout
Vietnam
BIDV Bank
7006
Link / APM Payout
Vietnam
Eximbank
7007
Link / APM Payout
Vietnam
Agribank
7008
Link / APM Payout
Vietnam
USDT Crypto ERC20
7009
Link / APM Payout
Vietnam
USDT Crypto BEP20
7010
Link / APM Payout
Vietnam
Asia Commercial Bank (QR service)
7061
Link / APM Payout
Vietnam
BIDV Bank (QR service)
7062
Link / APM Payout
Vietnam
Vietcombank (QR service)
7063
Link / APM Payout
Vietnam
Vietinbank (QR service)
7064
Link / APM Payout
Vietnam
Momo QR Payment (QR service)
7065
Link / APM Payout
Vietnam
Zalo QR Payment (QR service)
7066
Link / APM Payout
Vietnam
Zalo H5 Payment (H5 service)
7067
Link / APM Payout
Vietnam
Vietnam Prosperity Joint-Stock Commercial Bank (QR Service)
7068
Link / APM Payout
Vietnam
Military Commercial Bank (QR Service)
7069
Link / APM Payout
Vietnam
Techcombank (QR Service)
7070
Link / APM Payout
Vietnam
Krung Thai Bank
7011
Link / APM Payout
Thailand
Siam Commercial Bank
7012
Link / APM Payout
Thailand
Bangkok bank
7013
Link / APM Payout
Thailand
Kasikorn Bank
7014
Link / APM Payout
Thailand
Thai Military Bank
7015
Link / APM Payout
Thailand
Krungsri bank
7016
Link / APM Payout
Thailand
CIMB Thai Bank Public Company Limited
7017
Link / APM Payout
Thailand
Government Savings Bank
7018
Link / APM Payout
Thailand
United Overseas Bank (Thai) PCL.
7019
Link / APM Payout
Thailand
Government Housing Bank
7020
Link / APM Payout
Thailand
Hong Kong Shanghai Bank
7021
Link / APM Payout
Thailand
Standard Chartered Bank (Thai) PCL.
7022
Link / APM Payout
Thailand
Land and Houses Bank Public Company Limited
7023
Link / APM Payout
Thailand
Thai QR Payment
7071
Link / APM Payout
Thailand
USDT Crypto ERC20
7072
Link / APM Payout
Thailand
USDT Crypto BEP20
7073
Link / APM Payout
Thailand
Bank Central Asia
7024
Link / APM Payout
Indonesia
Bank Negara Indonesia
7025
Link / APM Payout
Indonesia
Bank Mandiri
7026
Link / APM Payout
Indonesia
Bank Rakyat Indonesia
7027
Link / APM Payout
Indonesia
Bank Artha Graha (Support VA Wallet Only)
7028
Link / APM Payout
Indonesia
Bank Bukopin (Support VA Wallet Only)
7029
Link / APM Payout
Indonesia
Bank Commonwealth (Support VA Wallet Only)
7030
Link / APM Payout
Indonesia
Bank Danamon (Support VA Wallet Only)
7031
Link / APM Payout
Indonesia
Bank Mega (Support VA Wallet Only)
7032
Link / APM Payout
Indonesia
Bank Maspion (Support VA Wallet Only)
7033
Link / APM Payout
Indonesia
Bank Mestika (Support VA Wallet Only)
7034
Link / APM Payout
Indonesia
Bank Panin (Support VA Wallet Only)
7035
Link / APM Payout
Indonesia
Bank Sumut (Support VA Wallet Only)
7036
Link / APM Payout
Indonesia
Bank Sinar Mas (Support VA Wallet Only)
7037
Link / APM Payout
Indonesia
Bank Btpn (Support VA Wallet Only)
7038
Link / APM Payout
Indonesia
CIMB Niaga (Support VA Wallet Only)
7039
Link / APM Payout
Indonesia
HSBC Indonesia (Support VA Wallet Only)
7040
Link / APM Payout
Indonesia
Maybank /bii (Support VA Wallet Only)
7041
Link / APM Payout
Indonesia
OCBC Indonesia (Support VA Wallet Only)
7042
Link / APM Payout
Indonesia
Bank Permata (Support VA Wallet Only)
7043
Link / APM Payout
Indonesia
UOB Indonesia (Support VA Wallet Only)
7044
Link / APM Payout
Indonesia
Bank Negara Indonesia (VA)
7074
Link / APM Payout
Indonesia
Bank Mandiri (VA)
7075
Link / APM Payout
Indonesia
Bank Rakyat Indonesia (VA)
7076
Link / APM Payout
Indonesia
Maybank Indonesia (VA)
7077
Link / APM Payout
Indonesia
Bank Sahabat Sampoerna (VA)
7078
Link / APM Payout
Indonesia
Bank Sinarmas (VA)
7079
Link / APM Payout
Indonesia
CIMB Niaga (VA)
7080
Link / APM Payout
Indonesia
Bank Permata (VA)
7081
Link / APM Payout
Indonesia
USDT Crypto ERC20
7082
Link / APM Payout
Indonesia
USDT Crypto BEP20
7083
Link / APM Payout
Indonesia
Boleto
4011
Link
Brazil
Direct PIX
4012
Link
Brazil
Boleto Flash Itau
4013
Link
Brazil
SEPA Credit Transfer
6000
APM Payout
EU
SEPA Transfer
6001
Link
EU
Virtual Banking
50033
Link / APM Payout
South Korea
EasyPaisa
56500
Link / APM Payout
Pakistan
JazzCash
56501
Link / APM Payout
Pakistan
FEDERAL UNIVERSITY DUTSE MICROFINANCE BANK
16175
APM Payout
Nigeria
Flutterwave Technology Solutions Limited
16191
APM Payout
Nigeria
Olabisi Onabanjo University Microfinance Bank
16273
APM Payout
Nigeria
G-XChange Inc. (GCash)
40000
Link / APM Payout
Philippines
PayMaya Philippines
40001
Link / APM Payout
Philippines
APM Payments can be requested using the Link API. When the Link API is requested, the corresponding APM Type ID must be supplied in the paymentTypeId field of the data object.
Link request example for APM Test Payment (1)
{
"amount": 700,
"accountId": "[email protected]",
"currency": "EUR",
"description": "Payment for products",
"invoiceId": "08072021-01",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/failure",
"pendingUrl": "https://example.com/pending",
"cancelUrl": "https://example.com/cancel",
"data": {
"personId": "success@bank",
"firstName": "John",
"lastName": "Deer",
"phone": "9555777666",
"address": "Avishkar Ram Maruti Naupada 66 2",
"paymentTypeId": 1
}
}Link request example for APM UPI Payment (2000)
{
"amount": 500,
"accountId": "[email protected]",
"currency": "INR",
"description": "Payment for products",
"invoiceId": "08072021-01",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/failure",
"pendingUrl": "https://example.com/pending",
"cancelUrl": "https://example.com/cancel",
"data": {
"personId": "success@bank",
"firstName": "John",
"lastName": "Deer",
"phone": "9555777666",
"address": "Avishkar Ram Maruti Naupada 66 2",
"paymentTypeId": 2000
}
}Link request example for APM PhonePe Payment (2006)
{
"amount": 500,
"accountId": "[email protected]",
"currency": "INR",
"description": "Payment for products",
"invoiceId": "08072021-01",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/failure",
"pendingUrl": "https://example.com/pending",
"cancelUrl": "https://example.com/cancel",
"data": {
"firstName": "John",
"lastName": "Deer",
"phone": "9555777666",
"address": "Avishkar Ram Maruti Naupada 66 2",
"paymentTypeId": 2006
}
}Link request example for BTC (10100)
{
"amount": 0.00045,
"currency": "BTC",
"description": "Payment for products",
"invoiceId": "11222344",
"accountId": "[email protected]",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/failure",
"pendingUrl": "https://example.com/pending",
"cancelUrl": "https://example.com/cancel",
"ip": "10.10.10.10",
"data": {
"paymentTypeId":10100
}
}Link request example for Virtual Banking, South Korea (50033)
{
"amount": 60000,
"accountId": "[email protected]",
"currency": "KRW",
"description": "Payment for products",
"invoiceId": "08072021-01",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/failure",
"pendingUrl": "https://example.com/pending",
"cancelUrl": "https://example.com/cancel",
"data": {
"personId": "17181927934",
"firstName": "John",
"lastName": "Deer",
"phone": "9555777666",
"address": "18-5, Chunui-dong",
"paymentTypeId": 50033
}
}Link request example for APM Netbanking in India (2014)
{
"amount": 500,
"accountId": "[email protected]",
"currency": "INR",
"description": "Payment for products",
"invoiceId": "08072021-01",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/failure",
"pendingUrl": "https://example.com/pending",
"cancelUrl": "https://example.com/cancel",
"data": {
"firstName": "John",
"lastName": "Deer",
"phone": "9555777666",
"address": "Avishkar Ram Maruti Naupada 66 2",
"paymentTypeId": 2014
}
}Link request example for certain methods. (1)
{
"amount": 100000.00,
"accountId": "[email protected]",
"currency": "THB",
"description": "Payment for products",
"invoiceId": "1928398740527",
"name": "John Deer",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/failure",
"pendingUrl": "https://example.com/pending",
"cancelUrl": "https://example.com/cancel",
"data": {
"firstName": "John",
"lastName": "Deer",
"paymentTypeId": 7022
}
}APM Payout request example for certain methods. (1)
{
"amount": 100000.00,
"accountId": "[email protected]",
"currency": "THB",
"description": "Payment for products",
"invoiceId": "1928398740527",
"name": "John Deer",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/failure",
"pendingUrl": "https://example.com/pending",
"cancelUrl": "https://example.com/cancel",
"data": {
"firstName": "John",
"lastName": "Deer",
"bankAccountNumber":"1000000000000001",
"paymentTypeId": 7022
}
}APM Payout request example for certain methods. (2)
{
"amount": 10002.00,
"currency": "THB",
"invoiceId": "16",
"name": "John Deer",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/failure",
"pendingUrl": "https://example.com/pending",
"cancelUrl": "https://example.com/cancel",
"data": {
"bankAccountNumber": "0000012345864",
"ifsc": "IFSC",
"paymentTypeId": 7088
}
}Link request example for APM with list of available banks in India (2060)
{
"amount": 500,
"accountId": "[email protected]",
"currency": "INR",
"description": "Payment for products",
"invoiceId": "08072021-01",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/failure",
"pendingUrl": "https://example.com/pending",
"cancelUrl": "https://example.com/cancel",
"data": {
"firstName": "John",
"lastName": "Deer",
"phone": "9555777666",
"address": "Avishkar Ram Maruti Naupada 66 2",
"paymentTypeId": 2060
}
}Link Request Example for SEPA Transfer (6001)
{
"amount": 80.55,
"accountId": "[email protected]",
"currency": "EUR",
"description": "Payment for products",
"invoiceId": "080720218279",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/failure",
"pendingUrl": "https://example.com/pending",
"cancelUrl": "https://example.com/cancel",
"data": {
"firstName": "John",
"lastName": "Deer",
"phone": "7999383979",
"address": "Prager Str 75 Tutzing Schleswig-Holstein",
"paymentTypeId": 6001
}
}Link request example for EasyPaisa (56500)
{
"amount": 10000,
"accountId": "[email protected]",
"currency": "PKR",
"description": "Payment for products",
"invoiceId": "08072021-01",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/failure",
"pendingUrl": "https://example.com/pending",
"cancelUrl": "https://example.com/cancel",
"ip": "10.10.24.65",
"data": {
"personId": "03014333611", // Payer account number
"firstName": "John",
"lastName": "Deer",
"phone": "03014333611",
"documentId": "3440289238550", // CNIC 13 symbols
"address": "18-5, Chunui-dong",
"paymentTypeId": 56500
}
}Link request example for JazzCash (56501)
{
"amount": 10000,
"accountId": "[email protected]",
"currency": "PKR",
"description": "Payment for products",
"invoiceId": "08072021-01",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/failure",
"pendingUrl": "https://example.com/pending",
"cancelUrl": "https://example.com/cancel",
"ip": "10.10.24.65",
"data": {
"personId": "03014333611", // Payer account number
"firstName": "John",
"lastName": "Deer",
"phone": "03014333611",
"documentId": "3440289238550", // CNIC 13 symbols
"address": "18-5, Chunui-dong",
"paymentTypeId": 56501
}
}Link request example for Bank Transfer, Nigeria (16401)
{
"amount": 1000,
"accountId": "[email protected]",
"currency": "NGN",
"description": "Payment for products",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/failure",
"pendingUrl": "https://example.com/pending",
"cancelUrl": "https://example.com/cancel",
"ip": "10.10.24.65",
"data": {
"paymentTypeId": 16401
}
}Link request example for G-XChange Inc. (GCash), Philippines (40000)
{
"amount": 100,
"accountId": "[email protected]",
"currency": "PHP",
"description": "Payment for products",
"invoiceId": "08072021-01",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/failure",
"pendingUrl": "https://example.com/pending",
"cancelUrl": "https://example.com/cancel",
"data": {
"firstName": "John",
"lastName": "Deer",
"phone": "03123456789", // Phone number format start from '03' + 9 digits numbers
"address": "Avishkar Ram Maruti Naupada 66 2",
"paymentTypeId": 40000
}
}Link request example for PayMaya Philippines (40001)
{
"amount": 100,
"accountId": "[email protected]",
"currency": "PHP",
"description": "Payment for products",
"invoiceId": "08072021-01",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/failure",
"pendingUrl": "https://example.com/pending",
"cancelUrl": "https://example.com/cancel",
"data": {
"firstName": "John",
"lastName": "Deer",
"phone": "03123456789", // Phone number format start from '03' + 9 digits numbers
"address": "Avishkar Ram Maruti Naupada 66 2",
"paymentTypeId": 40001
}
}APM Payout
POST https://api.odeonpay.com/payments/apm/payout
APM Payout include non-card transaction payouts. Goods examples of APM Payouts are payouts to e-wallets or bank accounts.
Headers
Authorization
string
HTTP Basic Authentication
Content-Type
string
application/json
Request Body
amount
number
Payout amount
accountId
string
Funds recipient e-mail address
currency
string
Payout currency
description
string
Payout description in text format
invoiceId
string
Order or invoice number
name
string
Funds recipient name
data
object
Additional data required for the payout processing. See request example for available fields in the data object
{
"model": {
"transactionId": 8432893,
"amount": 700.0,
"currency": "INR",
"invoiceId": "08072021-01",
"accountId": "[email protected]",
"name": "John Deer",
"statusCode": 10,
"status": "Created",
"reasonCode": 0,
"reason": "Approved"
},
"success": true,
"message": null
}APM Payout example for APM Test Payout (2)
{
"amount": 10,
"accountId": "[email protected]",
"currency": "EUR",
"description": "Payment for products",
"invoiceId": "1928398740527",
"name": "John Deer",
"data": {
"personId": "success@bank",
"phone": "9555777666",
"address": "Avishkar Ram Maruti Naupada 66 2",
"paymentTypeId": 2
}
}APM Payout Testing credentials for APM Test Payout (2)
success@bank
Successful payout test credentials
failure@bank
Failed payout test credentials
APM Payout example for UPI (3020)
{
"amount": 700,
"accountId": "[email protected]",
"currency": "INR",
"description": "Payment for products",
"invoiceId": "08072021-01",
"name": "John Deer",
"data": {
"personId": "9555777666@upi",
"phone": "9555777666",
"address": "Avishkar Ram Maruti Naupada 66 2",
"paymentTypeId": 3020
}
}APM Payout example to India bank account (3021)
{
"amount": 500,
"accountId": "[email protected]",
"currency": "INR",
"description": "Payment for products",
"invoiceId": "08072021-01",
"name": "John Deer",
"data": {
"personId": "24250100008333",
"phone": "9555777666",
"address": "Avishkar Ram Maruti Naupada 66 2",
"paymentTypeId": 3021,
"ifsc": "ABCD1234567"
}
}APM Payout request example for SEPA Credit Transfer (6000)
{
"amount": 10,
"accountId": "[email protected]",
"currency": "EUR",
"description": "Payment for products",
"invoiceId": "1928398740527",
"name": "John Deer",
"data": {
"bankAccountNumber": "LT837500018004669430",
"paymentTypeId": 6000
}
}APM Payout for Virtual Banking, South Korea (50033)
{
"amount": 1000,
"accountId": "[email protected]",
"currency": "KRW",
"description": "Payout",
"invoiceId": "123",
"name": "John Deer",
"data": {
"personId": "john123",
"bankName": "Kwangju Bank",
"bankAccountNumber": "123456789",
"bankAccountHolder": "John Doe"
}
}APM Payout request example for EasyPaisa (56500)
{
"amount": 10000,
"accountId": "[email protected]",
"currency": "PKR",
"description": "Payout",
"invoiceId": "123",
"name": "John Deer",
"data": {
"personId": "03401234567", // Payer account number
"phone": "03401234567",
"documentId": "3440289238550", // cnic
"paymentTypeId": 56500
}
}APM Payout request example for JazzCash (56501)
{
"amount": 10000,
"accountId": "[email protected]",
"currency": "PKR",
"description": "Payout",
"invoiceId": "123",
"name": "John Deer",
"data": {
"personId": "03401234567", // Payer account number
"phone": "03401234567",
"documentId": "3440289238550", // cnic
"paymentTypeId": 56501
}
}APM Payout request example for G-XChange Inc. (GCash), Philippines (40000)
{
"amount": 500,
"accountId": "[email protected]",
"currency": "PHP",
"description": "Payout",
"name": "John Deer",
"data": {
"personId": "03123456789", // Phone number format start from '03' + 9 digits numbers
"paymentTypeId": 40000
}
}APM Payout request example for PayMaya Philippines, Philippines (40001)
{
"amount": 500,
"accountId": "[email protected]",
"currency": "PHP",
"description": "Payout",
"name": "John Deer",
"data": {
"personId": "03123456789", // Phone number format start from '03' + 9 digits numbers
"paymentTypeId": 40001
}
}APM Payout request example for Nigeria
{
"amount": 1000,
"accountId": "[email protected]",
"currency": "NGN",
"description": "Payout",
"invoiceId": "1000047",
"name": "John Deer",
"data": {
"phone": "9988776655",
"bankAccountHolder": "John Doe", // Optional, name field used instead
"bankAccountNumber": "0800000071",
"paymentTypeId": 16346
}
}APM Payout is asynchronous operation. After the payout is requested, the request is created and sent to the processing system. The payout execution time depends on the processing system. When the payout is processed, the final status of the payout will be sent as a Notification.
APM Refund
POST https://api.odeonpay.com/payments/apm/refund
The method to return the funds of successfully completed payment operation
Headers
Authorization
string
HTTP Basic Authentication
Content-Type
string
application/json
Request Body
transactionId
integer
Transaction ID of successfully completed payment transaction
amount
number
Refund amount
{
"model": {
"transactionId": 8432893,
"amount": 700.0,
"currency": "INR",
"invoiceId": "08072021-01",
"accountId": "[email protected]",
"name": "John Deer",
"statusCode": 10,
"status": "Created",
"reasonCode": 0,
"reason": "Approved"
},
"success": true,
"message": null
}Request example of the refund
{
"transactionId": 8432820,
"amount": 700
}APM Refund is asynchronous operations. After the refund is requested, the request is created and sent to the processing system. The refund execution time depends on the processing system. When the refund is processed, the final status of the refund will be sent as a Notification.
Notifications
Notification is an HTTP request from the system to your site. Similar requests are also called callback or webhook. The system provides notifications about successful and unsuccessful payments.
Payment Success
The Success notification is performed once a payment is successfully completed. It serves the purpose of information about a payment: the system sends a request to a merchant's website address with payment information, and the merchant's site has to register the fact of payment.
Parameter
Type
Usage
Description
transactionId
Integer
Required
Transaction number in the system
amount
Number
Required
Amount
currency
String
Required
Currency
dateTime
String
Required
Date and time
invoiceId
String
Optional
Invoice or order number
accountId
String
Optional
Payer's identifier
operationTypeCode
Integer
Required
Transaction operation code
operationType
String
Required
Transaction operation ("Payment")
status
String
Required
Transaction status ("Completed")
statusCode
Integer
Required
Transaction status code
cardFirstSix
String
Required
Transaction Card PAN first 6 numbers
cardLastFour
String
Required
Transaction Card PAN last 4 numbers
cardType
String
Required
Card type (VISA, Mastercard, Amex)
cardExpDate
String
Required
Card expiry date in MM/YYYY format
name
String
Optional
Cardholder's name
token
String
Optional
Payment card's token. Returned only if accountId
was provided during the payment
Payment Failure
In the event of a payment failure, the merchant is able to receive a notification with transaction details and failure explanation.
Parameter
Type
Usage
Description
transactionId
Integer
Required
Transaction number in the system
amount
Number
Required
Amount
currency
String
Required
Currency
dateTime
String
Required
Date and time
invoiceId
String
Optional
Invoice or order number
accountId
String
Optional
Payer's identifier
operationTypeCode
Integer
Required
Transaction operation code
operationType
String
Required
Transaction operation ("Payment")
status
String
Required
Transaction status ("Declined")
statusCode
Integer
Required
Transaction status code
cardFirstSix
String
Required
Transaction Card PAN first 6 numbers
cardLastFour
String
Required
Transaction Card PAN last 4 numbers
cardType
String
Required
Card type (VISA, Mastercard, Amex)
cardExpDate
String
Required
Card expiry date in MM/YYYY format
name
String
Optional
Cardholder's name
reason
String
Required
Transaction failure reason
reasonCode
Integer
Required
Transaction failure reason code
Refund Success
The Refund Success notification is performed if a payment was refunded (fully or partially) on your initiative via the API or Back Office.
Parameter
Type
Usage
Description
paymentTransactionId
Integer
Required
Transaction number of the initial payment in the system
transactionId
Integer
Required
Refund transaction number in the system
amount
Number
Required
Refund amount
currency
String
Required
Currency
dateTime
String
Required
Date and time
invoiceId
String
Optional
Invoice or order number
accountId
String
Optional
Payer's identifier
operationTypeCode
Integer
Required
Transaction operation code
operationType
String
Required
Transaction operation ("Refund")
status
String
Required
Transaction status ("RefundCompleted")
statusCode
Integer
Required
Transaction status code
Refund Failure
The Refund Failure notification is performed if a payment refund request (full or partial) has failed.
Parameter
Type
Usage
Description
paymentTransactionId
Integer
Required
Transaction number of the initial payment in the system
transactionId
Integer
Required
Refund transaction number in the system
amount
Number
Required
Refund amount
currency
String
Required
Currency
dateTime
String
Required
Date and time
invoiceId
String
Optional
Invoice or order number
accountId
String
Optional
Payer's identifier
operationTypeCode
Integer
Required
Transaction Operation Code
operationType
String
Required
Transaction operation ("Refund")
status
String
Required
Transaction status ("Declined")
statusCode
Integer
Required
Transaction status code
reason
String
Required
Transaction failure reason
reasonCode
Integer
Required
Transaction failure reason code
Payout Success
The Payout Success notification is performed if funds were paid out on your initiative via the API or Back Office.
Parameter
Type
Usage
Description
transactionId
Integer
Required
Payout transaction number in the system
amount
Number
Required
Payout amount
currency
String
Required
Currency
accountId
String
Required
Payer's identifier
invoiceId
String
Optional
Invoice or order number
dateTime
String
Required
Date and time
operationTypeCode
Integer
Required
Transaction operation code
operationType
String
Required
Transaction operation ("CardPayout")
status
String
Required
Transaction status ("PayoutCompleted")
statusCode
Integer
Required
Transaction status code
Payout Failure
The Payout Failure notification is performed if funds payout request has failed.
Parameter
Type
Usage
Description
transactionId
Integer
Required
Payout transaction number in the system
amount
Number
Required
Payout amount
currency
String
Required
Currency
accountId
String
Required
Payer's identifier
invoiceId
String
Optional
Invoice or order number
dateTime
String
Required
Date and time
operationTypeCode
Integer
Required
Transaction operation code
operationType
String
Required
Transaction operation ("CardPayout")
status
String
Required
Transaction status ("Declined")
statusCode
Integer
Required
Transaction status code
reason
String
Required
Transaction failure reason
reasonCode
Integer
Required
Transaction failure reason code
Payment Check
The Payment Check notification is performed once a cardholder filled in a payment form and pressed the “Pay” button. It serves the purpose of payment validation: the system sends a request to a merchant's website address with payment information, and the website must validate and reply back if the payment has to be confirmed or rejected.
Parameter
Type
Usage
Description
transactionId
Integer
Required
Payment transaction number in the system
amount
Number
Required
Payment amount
currency
String
Required
Payment currency
dateTime
String
Required
Date and time
invoiceId
String
Required
Invoice or order number
accountId
String
Required
Payer's identifier
name
String
Required
Cardholder's name
operationTypeCode
Integer
Required
Transaction operation code
operationType
String
Required
Transaction operation ("Payment")
cardFirstSix
String
Required
Transaction Card PAN first 6 numbers
cardLastFour
String
Required
Transaction Card PAN last 4 numbers
cardType
String
Required
Card type (VISA, Mastercard, Amex)
cardExpDate
String
Required
Card expiry date in MM/YYYY format
status
String
Required
Transaction status ("Created")
statusCode
Integer
Required
Transaction status code
Payment Check notifications expects HTTP status 200 with response in JSON format with the required parameter code:
{"code":0}Response codes
Payment Check notification expects the code value "0" in order to proceed with the payment. Any other numeric value received with the response will reject the payment processing.
Notification confirmation
The system expects the 200 HTTP response in JSON format with the required parameter code equal to 0
Parameter
Type
Description
code
Integer
Notification confirmation code
Notification confirmation example
{"code":0}In case the System didn't receive the mentioned success code, notification sending will be repeated 5 times.
Notification validation
All the notifications have the Content-HMAC HTTP header which contains a validation value of a request which is calculated using the HMAC algorithm. If you need to verify authenticity and integrity of notifications, you can calculate a validation value on your side and compare it with the request value. The coincidence confirms that you received the notification we sent in the original form.
For notifications sent by POST method the message is represented by a request body.
Hash is calculated by SHA256 function;
The secret API is used as a key, which can be obtained in your Back Office;
The calculated value is passed in base64 encoding.
HMAC value calculation and encoding example
<?php
$data = '{"transactionId":512,"amount":30.45,"currency":"EUR"}';
$secret = '1234ABCD';
$hmac_data = hash_hmac('sha256', $data, $secret);
$hmac_content = base64_encode($hmac_data);
echo $hmac_content;
?>Output result:
MzVkMzBlMTdmMmVkNGJkNjFhMzFmNTdhODU0ZGQwZTYwZGU5MDg5MDRiODYyMTAzZmI0ZDAzMjRiMWJmNmM3Mw==The system sends notifications from the following address 34.77.206.110.
Request Signature Validation
Merchants can ensure the integrity and authenticity of the requests they send to our system by using a signature validation method. Each request must include the Content-HMAC HTTP header, which contains the validation value (signature).
How It Works:
HTTP Header: Merchants must send a
Content-HMACheader with each API request. This header contains the base64-encoded HMAC value used for validation.Request Body: The entire request body (the message) is used to generate the HMAC value.
HMAC Algorithm: The HMAC value is calculated using the SHA256 algorithm.
Signature Key: Merchants must use their signature key (available in their Back Office) as the key when generating the HMAC value.
Base64 Encoding: The calculated HMAC value is then encoded using base64.
HMAC value calculation and encoding example:
<?php
$data = '{"transactionId":512,"amount":30.45,"currency":"EUR"}';
$signatureKey = '1234ABCD';
$hmac_data = hash_hmac('sha256', $data, $signatureKey);
$hmac_content = base64_encode($hmac_data);
echo $hmac_content;
?>Expected Content-HMAC Output:
Content-HMAC Output:The merchant should send the Content-HMAC value in the request header:
Content-HMAC: MzVkMzBlMTdmMmVkNGJkNjFhMzFmNTdhODU0ZGQwZTYwZGU5MDg5MDRiODYyMTAzZmI0ZDAzMjRiMWJmNmM3Mw==Testing
Once you have an access to Back Office, it is in a test mode already which means that payments and other operations will take place in emulation mode. After you create a site in Back Office, it is automatically assigned a test mode.
Cards for Payment Operation tests
Card
Expiry
CVV
3-D Secure
Schema
Result
4111111111111111
12/24
123
Yes
Advanced
Success
4111111111111111
12/24
333
Yes
Advanced
Failure
4200000000000000
12/24
123
Yes
Redirect
Success
4200000000000000
12/24
333
Yes
Redirect
Failure
4242424242424242
12/24
123
No
None
Success
4242424242424242
12/24
333
No
None
Failure
Cards for Refund Operation tests
Card
Result
Description
4242424242424242
RefundCompleted
Successful refund (full or partial)
4111111111111111
Declined
All refund requests to this card will be declined by the system
4200000000000000
Created
Refund request will be created, but not processed further until the result is received from the acquiring bank
Cards for Card Payout Operation tests
Card
Result
Description
4242424242424242
PayoutCompleted
Successful payout to a card
4111111111111111
Declined
All payout requests to this card will be declined by the system
4200000000000000
Created
Payout request will be created, but not processed further until the result is received from the acquiring bank
Dictionaries
Transaction Status
ID
Status
Description
1
AwaitingAuthentication
Waiting for 3-D Secure authentication
4
Completed
Payment transaction successful completion
5
RefundCompleted
Refund transaction successful completion
7
PayoutCompleted
Payout transaction successful completion
10
Created
Transaction has been created
99
Declined
Transaction processing failure
Transaction Operations
ID
Operation
Description
1
Payment
Transaction operation when funds are charged from the credit card
2
Refund
Operation when funds are returned back to a credit card after the initial Payment operation
3
CardPayout
Operation when the funds are paid out to a credit card
Timezones
Timezone
Description
Pacific/Samoa
GMT-11:00
US/Hawaii
GMT-10:00
US/Alaska
GMT-09:00
America/Los_Angeles
GMT-08:00
US/Arizona
GMT-07:00
America/Mexico_City
GMT-06:00
US/East-Indiana
GMT-05:00
Atlantic/Bermuda
GMT-04:00
America/Santiago
GMT-03:00
America/Noronha
GMT-02:00
Atlantic/Azores
GMT-01:00
Europe/London
GMT+00:00
Europe/Paris
GMT+01:00
Europe/Riga
GMT+02:00
Europe/Moscow
GMT+03:00
Asia/Tbilisi
GMT+04:00
Asia/Yekaterinburg
GMT+05:00
Asia/Omsk
GMT+06:00
Asia/Tomsk
GMT+07:00
Singapore
GMT+08:00
Asia/Chita
GMT+09:00
Asia/Vladivostok
GMT+10:00
Australia/Sydney
GMT+11:00
Last updated
Was this helpful?