Current Checkout Controller Operations

This table is aligned directly with the current CheckoutPaymentController and its DTOs. Merchant operations require the merchantId header unless noted otherwise.

HTTP Endpoint Request Response
POST /payment/v1/checkout-payments/init InitCheckoutPaymentRequest InitCheckoutPaymentResponse
POST /payment/v1/checkout-payments/post-init PostInitCheckoutPaymentRequest InitCheckoutPaymentResponse
POST /payment/v1/checkout-payments/pre-init PreInitCheckoutPaymentRequest PreInitCheckoutPaymentResponse
POST /payment/v1/checkout-payments/complete CheckoutPaymentRequest CardPaymentResponse
POST /payment/v1/checkout-payments/3ds-init CheckoutPaymentRequest ThreeDSInitResponse
POST /payment/v1/checkout-payments/3ds-verify-complete VerifyThreeDSRequest CheckoutThreeDSVerifyCompleteResponse
POST /payment/v1/checkout-payments/3ds-verify-complete-for-failed-payment VerifyThreeDSForFailedPaymentRequest 204 No Content
POST /payment/v1/checkout-payments/point PointInquiryRequest PointInquiryResponse
GET /payment/v1/checkout-payments/{token} Path: token CardPaymentResponse
GET /payment/v1/checkout-payments/retrieve/{token} Path: token, header: partnerId CheckoutPaymentResponse

Flow-specific contracts

Request Required Optional/default
PostInitCheckoutPaymentRequest token, positive price, positive paidPrice, paymentGroup, items, buyerId paymentPhase=AUTH, callbackUrl=NO_CALLBACK_URL, buyerPayment=false
PreInitCheckoutPaymentRequest currency buyerId, customerNo, conversationId (max. 255), callbackUrl=NO_CALLBACK_URL, paymentPhase=AUTH, cardUserKey, customerTitle
CheckoutPaymentRequest Current CreatePaymentRequest fields and checkoutFormToken See the payment request contract.
VerifyThreeDSRequest 36-character pfCallbackToken, status, non-empty callbackParams —
PointInquiryRequest currency Card fields, items, and paidPrice; installment is fixed to 1.

ThreeDSInitResponse.data.htmlContent contains Base64-encoded HTML. Point inquiry returns point, pointPrice, loyaltyPoint, loyaltyPointPrice, totalPoint, totalPointPrice, and errorMessage.

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.
moneyBoxPrice decimal No Amount to be charged from MoneyBox. Defaults to 0. When greater than zero, moneyBoxUserId is required.
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

Parameter Type Mandatory Description
moneyBoxUserId long Conditional MoneyBox user identifier when moneyBoxPrice is greater than zero.
paymentPhase string No Payment phase. Defaults to AUTH.
enabledInstallments integer[] No Installment options displayed on the checkout page.
enabledInstallmentsForCommercial integer[] No Commercial-card installment options.
enabledBanks integer[] No Limits the available banks.
externalCustomerId string No Customer identifier in the merchant system; maximum 255 characters.
invoiceTotalAmount decimal No Invoice total associated with the payment.
storeCardEnable boolean No Enables card storage on the checkout page. Defaults to true.
cardHolder object No Cardholder name, email, and phoneNumber information.
expireAfterMinutes integer No Checkout token lifetime in minutes.
redirectOnFailure boolean No Redirects to the callback URL when payment fails. Defaults to false.
invoiceNo string No Invoice number related to the payment.
taxNumber string No Customer tax number.
customerEmail string No Customer email address.
description string No Payment description; maximum 255 characters.
informUrl string No Notification URL for supported merchant flows.

Payment item fields

Each object in items supports externalId, subExternalId, externalProductUniqueId, name, price, subMerchantId, subMerchantPrice, withHoldingPrice, productItemCode, skuCode, maturity, itemDetail, vatRate, and giftCard. The price field is required and cannot be negative. At most 250 items can be sent; identifier/name length limits are 50 characters for externalId and subExternalId, and 255 characters for externalProductUniqueId and name.

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.
tokenExpireDate localDateTime Yes The tokenExpireDate field represents the expiration timestamp for the payment page token. This is a value that indicates when both the payment token and the associated payment page URL will expire and become invalid.

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.
callbackUrlstringYesThe merchant URL that receives the checkout result.
merchantIdlongYesIdentifier of the merchant that owns the payment.
successbooleanYesIndicates whether verification and payment completion succeeded.
paymentOrderintegerNoOrder of the payment in a multi-payment flow.
conversationIdstringNoCorrelation value supplied in the initiation request.
paidPricedecimalYesTotal amount charged.
merchantPanelPaymentbooleanYesIndicates that the payment originated from the merchant panel.
redirectOnFailurebooleanNoIndicates whether the client should redirect to the callback URL after failure.

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
Field Type Description
pointPrice decimal Amount paid with card points.
giftCardPrice decimal Amount paid with a gift card.
loyaltyPointPrice decimal Amount paid with loyalty points.
additionalInstallment integer Additional installment count.
paymentGroup string Payment group.
paymentPhase string Payment phase such as AUTH.
cardToken string Stored-card token when available.
paidWithStoredCard boolean Indicates use of a stored card.
connectorType string Connector used to process the payment.
paymentError object Structured error details when the payment fails.
hostReference string Bank/host reference value.
authCode string Bank authorization code.
bankCode long Bank identifier.
subscriptionId long Related subscription identifier.
htmlContent string HTML content returned by supported payment flows.
bankCardHolderName string Cardholder name returned by the bank.
merchantName string Merchant branch name.
cardId long Stored-card identifier.
pfCommissionAmountForMerchant decimal Platform commission amount allocated to the merchant.
pfCommissionAmountForSubmerchant decimal Platform commission amount allocated to the submerchant.
pfCommissionRateForMerchant decimal Platform commission rate for the merchant.
pfCommissionRateForSubmerchant decimal Platform commission rate for the submerchant.
averageValor string Calculated average value date information.

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

Sample Codes