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_US

Parameter	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.

All query parameters passed to the redirect url (incl. description, accountId, successUrl, failureUrl, pendingUrl) should be URL encoded.

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: '[e-mail]' // 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.

Duplicate Requests Protection by invoiceId is disabled by default. Refer to you Account Manager in case the Protection has to be activated.

Test

POST https://api.odeonpay.com/test

The method to test the interaction with the API.

Headers

Name	Type	Description
Authorization	string	HTTP Basic authentication
Content-Type	string	application/json

200 The method returns a request status.

{"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

Name	Type	Description
Authorization*	string	HTTP Basic authentication
Content-Type*	string	application/json

Request Body

Name	Type	Description
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.

200

{
    "success": true,
    "message": null,
    "model": {
        "transactionId": 524,
        "amount": 40.11,
        "currency": "EUR",
        "invoiceId": "9276334",
        "accountId": "[e-mail]",
        "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": "[e-mail]",
	"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": "[e-mail]",
        "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": "[e-mail]",
        "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>

When authentication is done, payer will be returned to TermUrl with the MD and PaRes parameters passed in the POST method.

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

Name	Type	Description
Authorization*	string	HTTP Basic authentication
Content-Type*	string	application/json

Request Body

Name	Type	Description
transactionId*	integer	MD parameter value
paRes*	string	Received PaRes value

200

{
    "success": true,
    "message": null,
    "model": {
        "transactionId": 524,
        "amount": 40.11,
        "currency": "EUR",
        "invoiceId": "9276334",
        "accountId": "[e-mail]",
        "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

Name	Type	Description
Authorization*	string	HTTP Basic authentication
Content-Type*	string	application/json

Request Body

Name	Type	Description
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.

200

{
    "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

Name	Type	Description
Authorization*	string	HTTP Basic authentication
Content-Type*	string	application/json

Request Body

Name	Type	Description
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

200

{
    "success": true,
    "message": null,
    "model": {
        "transactionId": 2533,
        "amount": 12.30,
        "currency": "EUR",
        "invoiceId": null,
        "accountId": "[e-mail]",
        "name": "John Doe",
        "statusCode": 7,
        "status": "PayoutCompleted",
        "reasonCode": 0,
        "reason": "Approved"
    }
}

Request example

{
    "token": "8163-KS17-JV29-KF28",
    "amount": 12.30,
    "accountId": "[e-mail]",
    "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

Name	Type	Description
Authorization*	string	HTTP Basic authentication
Content-Type*	string	application/json

Request Body

Name	Type	Description
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

200

{
    "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": "[phone]",
        "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

Name	Type	Description
Authorization*	string	HTTP Basic authentication
Content-Type*	string	application/json

Request Body

Name	Type	Description
transactionId*	string	Transaction ID to check the status of

200

{
    "model": {
        "transactionId": 144221,
        "amount": 12.30,
        "currency": "EUR",
        "invoiceId": "11928485",
        "accountId": "[e-mail]",
        "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

Name	Type	Description
Authorization*	string	HTTP Basic authentication
Content-Type*	string	application/json

Request Body

Name	Type	Description
invoiceId*	string	Transaction Invoice ID to check the status of

200: OK

{
    "success": true,
    "message": null,
    "transactions": [
        {
            "transactionId": 501166,
            "amount": 2.54,
            "currency": "EUR",
            "invoiceId": "1781",
            "accountId": "[e-mail]",
            "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": "[e-mail]",
            "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

Name	Type	Description
Authorization*	string	HTTP Basic authentication
Content-Type*	string	application/json

Request Body

Name	Type	Description
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)

Name	Type	Description
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)

Name	Type	Description
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).

200

{
    "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": "[e-mail]",
  "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

Name	Type	Description
Authorization*	string	HTTP Basic authentication
Content-Type*	string	application/json

Request Body

Name	Type	Description
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.

200

{
    "success": true,
    "message": null,
    "transactions": [
        {
            "id": 16213,
            "statusId": 4,
            "status": "Completed",
            "currency": "USD",
            "amount": 65.77,
            "description": "Products Payment",
            "invoiceId": "132-33541-34",
            "accountId": "[e-mail]",
            "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.

Headers

Name	Type	Description
Authorization*	string	HTTP Basic authentication
Content-Type*	string	application/json

Request Body

Name	Type	Description
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.

200

{
    "success": true,
    "message": null,
    "model": {
        "transactionId": 356244,
        "amount": 10.66,
        "currency": "USD",
        "invoiceId": "990022",
        "accountId": "[e-mail]",
        "description": "Payment for products",
        "statusCode": 10,
        "status": "Created",
        "reasonCode": 0,
        "reason": "Approved"
    },
    "link": {
        "method": "get",
        "action": "https://checkout.odeonpay.com/?f8927-3928f-2398-3939"
    }
}

Request example

{
	"amount": 10.66,
	"currency": "USD",
	"description": "Payment for products",
	"invoiceId": "990022",
	"accountId": "[e-mail]",
	"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": "[phone]",
                "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

Name	Type	Description
Authorization*	string	HTTP Basic authentication
Content-Type*	string	application/json

200

{
    "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	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
India Bank Selection	2060	Link	India
UPI QR	2080	Link	India
Axis Bank	2081	Link / APM Payout	India	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Bandhan Bank	2082	Link / APM Payout	India	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Bank Of Baroda	2083	Link / APM Payout	India	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Federal Bank LTD	2084	Link / APM Payout	India	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
IDBI Bank	2085	Link / APM Payout	India	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
India Post Payment Bank	2086	Link / APM Payout	India	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Jammu and Kashmir Bank Limited	2087	Link / APM Payout	India	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Karnataka Bank Limited	2088	Link / APM Payout	India	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Lakshmi Vilas Bank	2090	Link / APM Payout	India	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
PAYTM Payments Bank LTD	2091	Link / APM Payout	India	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Ujjivan Small Finance Bank	2092	Link / APM Payout	India	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
UPI Payouts	3020	APM Payout	India
Bank Transfer Payouts	3021	APM Payout	India
Techcombank	7000	Link / APM Payout	Vietnam	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Sacombank	7001	Link / APM Payout	Vietnam	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Vietcombank	7002	Link / APM Payout	Vietnam	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Asia Commercial Bank	7003	Link / APM Payout	Vietnam	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
DongA Bank	7004	Link / APM Payout	Vietnam	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Vietinbank	7005	Link / APM Payout	Vietnam	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
BIDV Bank	7006	Link / APM Payout	Vietnam	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Eximbank	7007	Link / APM Payout	Vietnam	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Agribank	7008	Link / APM Payout	Vietnam	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
USDT Crypto ERC20	7009	Link / APM Payout	Vietnam	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
USDT Crypto BEP20	7010	Link / APM Payout	Vietnam	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Asia Commercial Bank (QR service)	7061	Link / APM Payout	Vietnam	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
BIDV Bank (QR service)	7062	Link / APM Payout	Vietnam	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Vietcombank (QR service)	7063	Link / APM Payout	Vietnam	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Vietinbank (QR service)	7064	Link / APM Payout	Vietnam	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Momo QR Payment (QR service)	7065	Link / APM Payout	Vietnam	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Zalo QR Payment (QR service)	7066	Link / APM Payout	Vietnam	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Zalo H5 Payment (H5 service)	7067	Link / APM Payout	Vietnam	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Vietnam Prosperity Joint-Stock Commercial Bank (QR Service)	7068	Link / APM Payout	Vietnam	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Military Commercial Bank (QR Service)	7069	Link / APM Payout	Vietnam	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Techcombank (QR Service)	7070	Link / APM Payout	Vietnam	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Vietnam QR	22011	Link	Vietnam	Link request example for certain methods. (1)
Krung Thai Bank	7011	Link / APM Payout	Thailand	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Siam Commercial Bank	7012	Link / APM Payout	Thailand	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Bangkok bank	7013	Link / APM Payout	Thailand	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Kasikorn Bank	7014	Link / APM Payout	Thailand	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Thai Military Bank	7015	Link / APM Payout	Thailand	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Krungsri bank	7016	Link / APM Payout	Thailand	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
CIMB Thai Bank Public Company Limited	7017	Link / APM Payout	Thailand	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Government Savings Bank	7018	Link / APM Payout	Thailand	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
United Overseas Bank (Thai) PCL.	7019	Link / APM Payout	Thailand	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Government Housing Bank	7020	Link / APM Payout	Thailand	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Hong Kong Shanghai Bank	7021	Link / APM Payout	Thailand	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Standard Chartered Bank (Thai) PCL.	7022	Link / APM Payout	Thailand	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Land and Houses Bank Public Company Limited	7023	Link / APM Payout	Thailand	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Thai QR Payment	7071	Link / APM Payout	Thailand	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
USDT Crypto ERC20	7072	Link / APM Payout	Thailand	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
USDT Crypto BEP20	7073	Link / APM Payout	Thailand	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
UOB Bank	7088	APM Payout	Thailand	{"success": true, "message": "Test message success"}
TMBThanachart Bank	7089	APM Payout	Thailand	{"success": true, "message": "Test message success"}
Bank Central Asia	7024	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Bank Negara Indonesia	7025	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Bank Mandiri	7026	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Bank Rakyat Indonesia	7027	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Bank Artha Graha (Support VA Wallet Only)	7028	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Bank Bukopin (Support VA Wallet Only)	7029	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Bank Commonwealth (Support VA Wallet Only)	7030	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Bank Danamon (Support VA Wallet Only)	7031	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Bank Mega (Support VA Wallet Only)	7032	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Bank Maspion (Support VA Wallet Only)	7033	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Bank Mestika (Support VA Wallet Only)	7034	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Bank Panin (Support VA Wallet Only)	7035	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Bank Sumut (Support VA Wallet Only)	7036	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Bank Sinar Mas (Support VA Wallet Only)	7037	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Bank Btpn (Support VA Wallet Only)	7038	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
CIMB Niaga (Support VA Wallet Only)	7039	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
HSBC Indonesia (Support VA Wallet Only)	7040	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Maybank /bii (Support VA Wallet Only)	7041	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
OCBC Indonesia (Support VA Wallet Only)	7042	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Bank Permata (Support VA Wallet Only)	7043	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
UOB Indonesia (Support VA Wallet Only)	7044	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Bank Negara Indonesia (VA)	7074	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Bank Mandiri (VA)	7075	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Bank Rakyat Indonesia (VA)	7076	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Maybank Indonesia (VA)	7077	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Bank Sahabat Sampoerna (VA)	7078	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Bank Sinarmas (VA)	7079	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
CIMB Niaga (VA)	7080	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
Bank Permata (VA)	7081	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
USDT Crypto ERC20	7082	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
USDT Crypto BEP20	7083	Link / APM Payout	Indonesia	Link request example for certain methods. (1)APM Payout request example for certain methods. (1)
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
BTC, Bitcoin	10100	Link	Worldwide	Link request example for BTC (10100)
Virtual Banking	50033	Link / APM Payout	South Korea	Link request example for Virtual Banking, South Korea (50033)APM Payout for Virtual Banking, South Korea (50033)
EasyPaisa	56500	Link / APM Payout	Pakistan	Link request example for EasyPaisa (56500) APM Payout request example for EasyPaisa (56500)
JazzCash	56501	Link / APM Payout	Pakistan	Link request example for JazzCash (56501) APM payout request example for JazzCash (56501)

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": "[e-mail]",
        "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": "[e-mail]",
        "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": "[e-mail]",
        "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": "[e-mail]",
  "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": "[e-mail]",
        "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": "[e-mail]",
        "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": "[e-mail]",
 "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": "[e-mail]",
 "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": "[e-mail]",
        "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": "[e-mail]",
	"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": "[e-mail]",
    "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": "[e-mail]",
    "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
    }
}

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

Name	Type	Description
Authorization	string	HTTP Basic Authentication
Content-Type	string	application/json

Request Body

Name	Type	Description
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

200

{
    "model": {
        "transactionId": 8432893,
        "amount": 700.0,
        "currency": "INR",
        "invoiceId": "08072021-01",
        "accountId": "[e-mail]",
        "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": "[e-mail]",
	"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)

personId	Result
success@bank	Successful payout test credentials
failure@bank	Failed payout test credentials

APM Payout example for UPI (3020)

{
	"amount": 700,
	"accountId": "[e-mail]",
        "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": "[e-mail]",
        "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": "[e-mail]",
	"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": "[e-mail]",
	"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": "[e-mail]",
    "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": "[e-mail]",
    "currency": "PKR",
    "description": "Payout",
    "invoiceId": "123",
    "name": "John Deer",
    "data": {
        "personId": "03401234567", // Payer account number
        "phone": "03401234567",
        "documentId": "3440289238550", // cnic
        "paymentTypeId": 56501
    }
}

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

Name	Type	Description
Authorization	string	HTTP Basic Authentication
Content-Type	string	application/json

Request Body

Name	Type	Description
transactionId	integer	Transaction ID of successfully completed payment transaction
amount	number	Refund amount

200

{
    "model": {
        "transactionId": 8432893,
        "amount": 700.0,
        "currency": "INR",
        "invoiceId": "08072021-01",
        "accountId": "[e-mail]",
        "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.

Enabling and disabling notifications as well as setting addresses and notification formats is configured in Back Office.

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-HMAC header 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:

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

Type in "4" as the 3-D Secure passphrase

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