Checkout Page

Payments made through the checkout page are made in 2 steps: initiation and completion. The launch request sends a request to the OderoPay API to create the form. As a result of this request, 2 values are returned to the sender of the request. One of these values is token and the other is pageUrl. After this step, the URL returned by pageUrl is opened in the browser or displayed with an iframe. iframe=True parameter must be added to this URL value to be able to render with an iframe. After the payment process, the form is sent with the token value of the url address in the callbackUrl parameter sent when creating the payment form. A card can be saved using the checkout page and payment can also be made with that saved card later on.

Creating Checkout Page

URL

The endpoint and http method used to initiate the checkout page are:

HTTP Metod URL
POST /payment/v1/checkout-payments/init

Payment Initiation Request Settings

Payments to be made through the common payment page require the callbackUrl parameter to be sent, unlike other payments. In this regard, the following are the parameters required to initiate a payment with 3D Secure:

Parameter Type Mandatory Description
conversationId string No A "boomerang" value that can be sent with a request and received with a response. It can be used to link different queries together. Usually, the order number associated with the payment is used from the member business.
price decimal Yes Total payment amount. The sum of the product/service amounts in the cart must be equal to this amount.
paidPrice decimal Yes The total amount paid by the customer is calculated by including differences such as commissions and discounts. In the case of fully or partially collected payments from the wallet, the amount to be withdrawn from the wallet is also included in this amount.
walletPrice decimal No The amount to be charged from the wallet of the buyer specified in the buyerId parameter. It is mandatory to send in payments that will be deducted from the wallet in part or in full. It can be sent as 0 in case of full card payments or buyerId. (Default: 0)
buyerId long No The payee ID to which the payment is associated. This refers to the ID value in OderoPay's systems, not the ID value in the member business's own systems.
cardUserKey string No User's saved card key, see: Card Storage
currency Currency Yes Currency
paymentGroup PaymentGroup Yes Payment Groups
callbackUrl string Yes• The address that will be used to deliver the result from the bank to the member business for payments made with 3D Secure.
items PaymentItem[] Yes Payment breakdown information. At least one split must be sent and the sum of the sums of the splits sent must be equal to the price field.
plan PaymentPlan No•• Information for late payment. All fields have to be sent.

•This field, which is not mandatory under normal conditions, is highlighted because it is mandatory for payments made through the Checkout Page

••This field is mandatory if paymentGroup is SUBSCRIPTION

Return Parameters

The parameters resulting from a payment operation with the Common Payment page must comply with the rules specified in the Response Parameters section of the API documentation login page. In the absence of a system or build error, the subparameters of the object returned in the data parameter are:

Parameter Type Always Available Description
token string Yes The unique uuid4 value generated for the common Payment page and payment transaction.
pageUrl string Yes This includes the address of the page the user should be redirected to. When you go to this page through a browser, a shared payment page opens.

3D Secure

The 3D Secure payment process, which begins with a request to create a payment form sent by a member business, continues with confirmation by the user.

After the user enters the verification code sent to him, the verification result is transferred to the Odero API by the respective bank. The Odero API reconciles the result it receives with some information about the payment, and sends a request to the callbackUrl sent by the member business in the request to initiate the payment.

Parameters Passed to Callback URL

The following parameters are passed using the HTTP POST method as a form variable. The parameters included in the request that will be sent by Odero to the callbackUrl after confirmation are as follows:

Parameter Name Type Always Available Disclosure
token string Yes The unique uuid4 value generated for the common Payment page and payment transaction.
multiPayment boolean No It means that the payment transaction is done in a piecemeal manner.
paymentIdList long[] No It is a list containing payment id(s).
subscriptionId long No The id value of a successful redial. Returned when PaymentGroup SUBSCRIPTION is equal.

Check payment

Payments made using the shared payment page can be investigated with a token value. The URL and request, response data used for the research operation are given below.

URL

Below is the information about the endpoint and http method used to initiate payment from the shared payment page:

HTTP Method URL
GET /payment/v1/checkout-payments/{token}

Return Parameters

The parameters resulting from a payment operation with the Common Payment page must comply with the rules specified in the Response Parameters section of the API documentation input page. In the absence of a system or build error, the sub parameters of the object output in the data parameter are as follows:

Parameter Name Type Always Available Disclosure
id long Yes Payment ID
createdDate date Yes The date the payment was first created
updatedDate date Yes Payment Renewal Date
orderId string Yes A unique ID number generated in connection with the payment. It is created by Odero for full wallet payments and by the bank in other cases
price decimal Yes Total basket amount of payment
paidPrice decimal Yes Total amount charged
walletPrice decimal Yes Amount taken from wallet
paymentType PaymentType Yes Payment Types
currency Currency Yes Currency
paymentStatus PaymentStatus Yes Payment Statuses
conversationId string No The conversationId value sent by the member business in the payment request
paymentCard PaymentCard Yes Card and fee information related to payment
paymentRefunds PaymentRefund[] Yes List of chargebacks
paymentTransactions PaymentTransaction[] Yes Details of the breakdowns included in the payment

Payment Card and Commission Information

Sent with all charges including wallet charges.

Parameter Name Type Always Available Disclosure
cardType CardType No Card Types Included in full or partial card payments. Indicates the type of card
cardAssociation CardAssociation No Card Associations Includes full or partial card payments. Shows the institution to which the card is connected
cardBrand string No It is included in full or partial card payments. It has the same price as cardBrand in the card details in the payment request
cardHolderName string No It is included in full or partial card payments. It reflects the name and surname of the card holder
binNumber string No It is included in full or partial card payments. Represents the first 6 digits of the card number
lastFourDigits string No It is included in full or partial card payments. Represents the last 4 digits of the card number
installment integer Yes Shows the number of payment installments. The grades he can get: 1, 2, 3, 6, 9, and 12
isThreeDS boolean No It is included in full or partial card payments. Indicates whether the payment was made with 3D Secure
mdStatus integer No MD Status included in payments made with 3D Secure and fully or partially debited from the card. Shows 3D Secure approval status
pfCommissionRateAmount decimal Yes The amount of commission received by Odero as a payment intermediary
merchantCommissionRate decimal Yes Commission rate applied to the payment by the member business
merchantCommissionRateAmount decimal Yes The total amount of the commission fee received from the payment by the member business
error Error No Occurs in payments that end in error. Contains error information

Payment Cancellation Information

Contains detailed information on full refunds. The parameters included in this data are listed in the table below:

Parameter Name Type Always Available Disclosure
id long Yes The Odero-generated ID of the cancellation operation
createdDate date Yes Cancellation date
refundStatus string Yes Refund Statuses
refundDestinationType RefundDestinationType Yes Refund Types
price decimal Yes Canceled amount
refundBankPrice decimal Yes Credited back to the card after cancellation
refundWalletPrice decimal Yes Deposited back to wallet after cancellation
conversationId string Yes The conversationId value sent by the member business in the cancellation request
paymentType PaymentType Yes Withdrawal type of canceled payment
error Error No Occurs if cancellation fails. Contains error information

Information Regarding Payment Allocation

This includes allocation information sent when a payment request is made, the pricing of a payment based on these allocations, and refund items related to remittances and breakage.

Parameter Name Type Always Available Disclosure
id long Yes ID of payment split
createdDate date Yes The date on which the distribution of payment was created
externalId string No The external ID associated with the payment split sent in the payment request
transactionStatus TransactionStatus Yes A value indicating the remittance status of the allocation
transactionStatusDate date Yes Shows the last date when the remittance status for the allocation changed
price decimal Yes The amount of payment distribution in the basket
paidPrice decimal Yes The respective institution's share of the total amount charged for payment
walletPrice decimal Yes The share of the total amount taken from the wallet for payment to the relevant institution
merchantPayoutAmount decimal Yes The share of the money to be sent to the member business in connection with the payment according to the corresponding distribution
subMerchantId long No The ID of the sub-member business to which the payment split is associated
subMerchantName string Yes The payment split takes place when the sub-member is associated with the business. This includes the name of the relevant member business
subMerchantPrice decimal Yes The payment split takes place when the sub-member is associated with the business. From the payment amount, the share of the total amount to be transferred to the sub-member business is the corresponding distribution
subMerchantPayoutRate decimal Yes Occurs if the sub-member of the payment distribution is related to the business. The sub-member associated with payment is the ratio of money sent to the member business to money sent to the member business
subMerchantPayoutAmount decimal Yes The payment split takes place when the sub-member is associated with the business. The payment related sub-member represents the amount to be sent to the business
payout Payout Yes This includes the distribution of remittance amounts between the member business, sub-member business, and Odero in connection with the payment distribution
paymentTransactionCard PaymentTransactionCard Yes Card and commission fee information related to payment distribution
paymentTransactionRefunds PaymentTransactionRefund[] Yes List of full or partial refund details related to payment split

Payment Allocation Card and Commission Information

This includes card and commission fee information related to payment split

Parameter Name Type Always Available Disclosure
merchantCommissionRate decimal Yes Commission rate applied to the payment by the member business
merchantCommissionRateAmount decimal Yes The share of payment distribution from the amount of commission received from the payment by the member business
pfCommissionRateAmount decimal Yes The share of payment distribution from the amount of commission received by Odero as a payment intermediary

Payment Distribution Distribution of Remittance

This includes sharing the share of the payment transfer between the member business, the sub-member business and Odero.

The currency of money distribution is always AZN or TRY depending on the country, therefore, there will be an exchange rate difference in payments made with other currencies. These differences are specified in the pfConversionRate and pfConversionRateAmount fields.

Parameter Name Type Always Available Disclosure
paidPrice decimal Yes The share of the total amount withheld for payment according to the appropriate distribution
currency Currency Yes See: Currency
merchantPayoutAmount decimal Yes The share of the value of the money in currency to be sent to the member business in connection with the payment, according to the corresponding distribution
subMerchantPayoutAmount decimal Yes The share of the value of the money in currency to be sent to the sub-member business in connection with the payment according to the appropriate distribution
pfCommissionRateAmount decimal Yes Regarding the payment, the share of the value of the money in currency to be sent to Odero as a payment intermediary institution
pfConversionRate decimal Yes The exchange rate difference on which Odero is based on remittances made in a currency other than.
pfConversionRateAmount decimal Yes Exchange rate difference received by Odero for remittances made in currencies other than currency.

Refund Information Related to Payment Allocation

Information on fully or partially successful or unsuccessful refunds related to payment distribution

Parameter Name Type Always Available Disclosure
id long Yes The Odero-generated ID of the cancellation operation
createdDate date Yes Cancellation date
refundStatus string Yes Refund Statuses
refundDestinationType RefundDestinationType Yes Refund Types
price decimal Yes Canceled amount
refundBankPrice decimal Yes Credited back to the card after cancellation
refundWalletPrice decimal Yes Deposited back to wallet after cancellation
conversationId string Yes The conversationId value sent by the member business in the cancellation request
paymentType PaymentType Yes Withdrawal type of canceled payment
isAfterSettlement boolean Yes Whether the refund is made after the distribution has been remitted
error Error No Occurs if cancellation fails. Contains error information