Below is the information about the endpoint and http method used to receive the payment:
| HTTP Method | URL |
|---|---|
POST |
/payment/v1/card-payments |
| Parameter name | 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) |
installment |
integer |
Yes | The number of payments from which payment will be taken. It can be sent as "1" for a single payment. Possible values: 1, 2, 3, 6, 9 and 12. |
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. |
currency |
Currency |
Yes | see : Currency Currency in which payment will be made. |
paymentGroup |
PaymentGroup |
Yes | see : Payment groups |
paymentPhase |
PaymentPhase |
No | see: Payment phases |
card |
Card |
No | (see Card Information) Information about the card used for payment. If the payment is fully covered by wallet funds (i.e., paidPrice and walletPrice are equal), this field is optional. |
posAlias |
string |
No | Used for TOKENGATE payments. If this field is filled, the payment will be processed through the specified POS (see: Payment Gateway). |
items |
PaymentItem[] |
Yes | (see: Information about Payment Distribution) Information about the distribution of payments. At least one part must be sent, and the sum of the sent parts must be equal to the value in the price field. |
Required for full or partial payment by card. This can include Prepaid, Credit, or Debit cards, as well as payment with a previously saved card.
If the cardUserKey field in the submitted card data is filled, then the fields in the section Information about the saved card are valid. Otherwise, see: Information about Debit, Credit, or Prepaid card.
| Parameter name | Type | Mandatory | Description |
|---|---|---|---|
cardHolderName |
string |
Yes | Cardholder's Name/Surname |
cardNumber |
string |
Yes | Card Number |
expireYear |
string |
Yes | Year of Card Expiry |
expireMonth |
string |
Yes | Month of Card Expiry |
cvc |
string |
Yes | Card Verification Code |
storeCardAfterSuccessPayment |
boolean |
No | If the payment is successful, save the card (Default: false) |
cardAlias |
string |
No | Name to be assigned to the card if the card is saved after a successful payment |
| Parameter name | Type | Mandatory | Description |
|---|---|---|---|
cardUserKey |
string |
Yes | Key of the saved card |
cardToken |
string |
Yes | Token of the saved card |
All payments must be submitted in one or more splits. The sum of the price fields of the submitted splits must be equal to the value in the payment price field.
| Parameter name | Type | Mandatory | Description |
|---|---|---|---|
name |
string |
Yes | Name of the product or service to which the payment relates |
price |
decimal |
Yes | Amount in the basket for the corresponding item or service |
externalId |
string |
No | Value of the external identifier representing the corresponding product or service. Typically, the identifier value in this section is used in the merchant's business system. |
subMerchantId |
long |
No | Identifier of the sub-merchant providing the product or service. |
subMerchantPrice |
decimal |
No | Amount that will be allocated from the payment to the sub-merchant. Must be submitted if the subMerchantId field is filled. |
The parameters returned as a result of the payment transaction process also adhere to the rules specified in the [Return Formats](/api#output-formats) section on the main page of the API documentation. In the absence of a systematic or structural error, the sub-parameters of the object returned in the data parameter are as follows:
| Parameter name | Type | Always Present | Description |
|---|---|---|---|
conversationId |
string |
No | The value of conversationId sent by the merchant as part of the payment request. |
id |
long |
Yes | Payment ID |
createdDate |
date |
Yes | Date of payment |
price |
decimal |
Yes | Total amount of the payment in the basket |
paidPrice |
decimal |
Yes | Total amount of the fee paid by the customer. In the case of full or partial payment deducted from the wallet, this amount also includes the amount to be withdrawn from the wallet. |
walletPrice |
decimal |
Yes | Amount withdrawn from the wallet |
currency |
string |
Yes | Payment currency |
buyerId |
long |
No | Value indicating the identifier of the corresponding participant in payments associated with the receiving participant. |
installment |
integer |
Yes | Number of installments by which the payment will be received. Possible values: 1, 2, 3, 6, 9, and 12. |
paymentType |
PaymentType |
Yes | see Payment Types |
paymentGroup |
PaymentGroup |
Yes | see Payment Groups |
paymentStatus |
PaymentStatus |
Yes | see Payment Statuses |
paymentPhase |
PaymentPhase |
Yes | see Payment Phases |
isThreeDS |
boolean |
Yes | Indicates whether the payment was made using 3D Secure |
merchantCommissionRate |
decimal |
Yes | The commission rate applied to the merchant's payment |
merchantCommissionRateAmount |
decimal |
The commission rate applied to the merchant's payment. | Yes |
merchantCommissionRate |
decimal |
Yes | The commission rate applied to the merchant's payment. |
merchantCommissionRateAmount |
decimal |
Yes | Total amount of commission received from the merchant's payment. It is equal to the difference between paidPrice and price. |
pfCommissionRateAmount |
decimal |
Yes | Size of the commission received from the payment by Odero as a payment intermediary. |
cardUserKey |
string |
No | During the request, for the storeCardAfterSuccessPayment field in the card information, the value is set to true for submitted payments. Represents the saved key of the registered card after successful payment. |
cardToken |
string |
No | During the request, the storeCardAfterSuccessPayment field in the card information has a value of true for submitted payments. Indicates the saved code of the card registered after successful payment. |
paidWithStoredCard |
boolean |
Yes | Indicates whether the payment is made with a stored card. |
binNumber |
string |
No | Occurs when paying with a card in full or in part. Indicates the first 6 digits of the card number. |
lastFourDigits |
string |
No | Occurs when paying with a card in full or in part. Indicates the last 4 digits of the card number. |
cardType |
CardType |
No | (see Card Types) Occurs when paying with a card in full or in part. Indicates the type of card. |
cardAssociation |
CardAssociation |
No | (see: Card Associations) Occurs when paying with a card in full or in part. Indicates the card organization that issued the card. |
cardBrand |
string |
Yes | Occurs when paying with a card in full or in part. It has the same value as cardBrand in the card details in the payment request. |
paymentTransactions |
PaymentTransaction[] |
Yes | See: Output data of payment distribution |
It includes information about the breakdown of payments, prices, and money transfers based on the payment breakdown submitted when making a payment request.
| Parameter name | Type | Always present | Description |
|---|---|---|---|
id |
long |
Yes | Payment ID |
externalId |
string |
No | Value of the external identifier associated with the payment split, sent in the payment request. |
name |
string |
Yes | Name of the product or service referenced by the payment split sent in the payment request. |
transactionStatus |
TransactionStatus |
Yes | See: Statuses of money transfers) Value indicating the transfer status for the distribution. |
price |
decimal |
Yes | Total amount of the payment in the basket. |
paidPrice |
decimal |
Yes | Total amount paid by the customer. In the case of full or partial payment from the wallet, this amount also includes the amount eligible for withdrawal from the wallet. |
walletPrice |
decimal |
Yes | Amount deducted from the wallet |
merchantCommissionRate |
decimal |
Yes | Commission rate applied to the merchant's payment |
merchantCommissionRateAmount |
decimal |
Yes | Total amount of commission received from the merchant's payment. It is equal to the difference between paidPrice and price |
pfCommissionRateAmount |
decimal |
Yes | Amount of commission received by TokenPay as a payment intermediary |
merchantPayoutAmount |
decimal |
Yes | Portion of money to be sent to the merchant in connection with the payout, according to the respective distribution. |
subMerchantId |
long |
No | Identifier of the sub-merchant associated with the payment split |
subMerchantName |
string |
Yes | Fee splitting occurs when a sub-merchant is associated with a business. Contains the name of the corresponding participating company. |
subMerchantPrice |
decimal |
Yes | Fee splitting occurs when a sub-merchant is associated with a business. This is the share of the total amount to be transferred to the sub-participant business according to the respective distribution. |
subMerchantPayoutRate |
decimal |
Yes | Fee splitting occurs when a sub-merchant is associated with a business. This is the ratio of money to be sent to the sub-merchant to the money to be sent to the merchant. |
subMerchantPayoutAmount |
decimal |
Yes | Fee splitting occurs when a sub-merchant is associated with a business. Represents the amount that will be sent to the sub-merchant. |
blockageResolvedDate |
date |
Yes | Date of resolution of the blocking period required for sending money. |
payout |
Payout |
Yes | (see Distribution of pay remittance distribution) This includes the distribution of amounts of money transfers between merchants, sub-merchants, and Odero in connection with payment splitting. |
This involves the distribution of the share of the payment transfer among merchants, sub-merchants, and Odero.
The payout currency is always AZN, so there will be an exchange rate difference for payments in other currencies. These differences are specified in the pfConversionRate and pfConversionRateAmount fields.
| Parameter name | Type | Always present | Description |
|---|---|---|---|
paidPrice |
decimal |
Yes | Share of the total amount withheld for payout according to the respective distribution. |
currency |
Currency |
Yes | Payout Currency |
merchantPayoutAmount |
decimal |
Yes | Share of the money value in AZN currency that will be sent to the merchant in connection with the payout, according to the respective distribution. |
subMerchantPayoutAmount |
decimal |
Yes | Share of the money value in AZN currency that will be sent to the sub-merchant in connection with the payout, according to the respective distribution. |
pfCommissionRateAmount |
decimal |
Yes | Share of the money value in AZN currency that will be sent to Odero in connection with the payout, according to the respective distribution. |
pfConversionRate |
decimal |
Yes | Exchange rate difference that Odero is based on for money transfers made in a currency other than AZN. For AZN, it is 0 in payments. |
pfConversionRateAmount |
decimal |
Yes | Exchange rate difference earned by Odero for money transfers made in currencies other than AZN. For AZN, it is 0 in payments. |