Charge request
Acquirers might apply various scenarios and transaction flows to process card payments for your billing scheme. It would make you implement different request types if you work with several acquirers or change your acquiring partner.
UnonaPay suggests using a single charge request which unifies the process of handling payments by saved card details.
When the UnonaPay system receives the charge request, it automatically modifies this request either to a payment or to an authorization operation. It depends on what transaction flow is supported by your acquirer which will process a payment. Moreover, if the charge request is modified to the authorization request, UnonaPay automatically sends the capture request.
In the back office the charge request is reported respectively to the type of the processed transaction, i.e. either as a payment or as an authorization and a capture.
Request
Send the POST
request to https://gateway.unonapay.com/services/credit_cards/charges
with the following parameters:
Parameter | Type | Description |
---|---|---|
request | object | |
amount * required |
integer | An amount in minimal currency units (for example $32.45 must be sent as 3245). |
currency * required |
string | A currency in the ISO-4217 format (for example USD). |
description * required |
string(255) | A short order description. |
tracking_id | string(255) | Your transaction or order ID. Please, use unique values to get the relevant transaction information by query requests. Otherwise, you get informed on the first transaction that matches tracking_id . |
expired_at | string | Date and time till a transaction should be finalized. Use ISO 8601 format: YYYY-MM-DDThh:mm:ssTZD, where YYYY – year (for example 2019), MM – month (for example 02), DD – day (for example 09), hh – hours (for example 18), mm – minutes (for example 20), ss – seconds (for example 45), TZD – time zone (+hh:mm или –hh:mm). If a payment is not paid till the indicated date, the transaction status is set to expired . |
duplicate_check | boolean | true or false . Used to avoid payment duplicates. By default, it is set to true , so requests with the same amount and number or token within 30 seconds will be rejected. |
dynamic_billing_descriptor | string | Dynamic billing descriptor. |
language | string | The language of your checkout page. It also specifies the language of email notifications sent out to your customers, if customer notifications are enabled. English (en ) is set by default. Possible values of language parameter. |
notification_url | string | URL where the system should send the notifications about a transaction. The notification request format matches the transaction response format. |
verification_url | string | A URL where the system should send the transaction verification. The verification request format matches the transaction response format. |
return_url * conditionally required |
string | A URL on the merchant side where UnonaPay should redirect the customer after 3-D Secure verification is finished. The parameter is mandatory if your merchant account is 3-D Secure enabled. Contact your account manager for more details. |
test | boolean | true or false . The transaction is processed as a test if the parameter is set to true . |
credit_card | object | A section of card credentials. |
number * required |
string | A card number. The length is from 12 to 19 digits. |
verification_value * required |
string | 3- or 4-digit security code (CVC2, CVV2 or CID depending on the credit card brand). It can be sent along with the token value, UnonaPay will transmit the card details with the given CVC2/CVV2/CID to your acquirer. |
holder * required |
string | A cardholder name as it appears on the card. The maximal length is 32 characters. |
exp_month * required |
integer | A card expiration month indicated with two digits (for example, 01). |
exp_year * required |
integer | A card expiration year indicated with four digits (for example, 2026). |
token * conditionally required |
string | A card token received earlier. The parameter is mandatory if you do not send card credentials. If a card token is used, you should specify the additional_data.contract parameter. |
skip_three_d_secure_verification | boolean | The parameter is used when you want your customer skip the 3-D Secure verification. Contact the Tech Support Team to check if you can apply this parameter. If true , UnonaPay doesn't launch the 3-D Secure verification for charge requests when a card token is submitted. Set to false , by default.The force_three_d_secure_verification parameter overrides the skip_three_d_secure_verification parameter, if both are set to true . |
force_three_d_secure_verification | boolean | The parameter enables the option to make the 3-D Secure verification check mandatory for the customer. Contact the Tech Support Team to check if you can apply this parameter. If true , UnonaPay forces the 3-D Secure verification for charge requests when a card token is submitted. Set to false , by default.The force_three_d_secure_verification parameter overrides the skip_three_d_secure_verification parameter, if both are set to true . |
additional_data | object | A section with additional transaction data. Check with the Support Team if you should send any section parameters. |
p2p | object | A parameter section for AFT transactions. |
service_id * conditionally required |
string | Request the parameter value from your manager. |
service_extension * conditionally required |
string | Request the parameter value from your manager. |
excluded_gateways | array | An array for working with cascading payments |
masterpass | object | A Masterpass service section. |
params | object | A section for Masterpass parameters. |
session | string | A user session ID. |
receipt_text | array | Text added to the customer notification. Submit it as an array of strings, for example ["First line", "Second line"] . |
contract | array | An array of elements:recurring - UnonaPay provides a card token to use for recurrent payments when customers are not required to enter their card data again. Customers indicate their full card details including CVC/CVV codes and pass the 3-D Secure verification only during the initial payment;oneclick - UnonaPay provides a card token for the oneclick payment flow, when the customer is redirected to the checkout page with the prefilled card details and is just required to enter the CVC/CVV code and pass the 3-D Secure verification to complete the payment;credit - UnonaPay provides a card token to use for a payout transaction;card_on_file - UnonaPay returns a card token, so you can link it to the customer account and use it for payments initiated by the customer or by your application. See card_on_file section below for use cases. Note! The card_on_file option might not be supported by your acquirer. If you want to use the card_on_file option, please, contact your account manager. |
avs_cvc_verification | object | AVS/CVC verification. |
card_on_file | object | A section specifying the option parameters which are transmitted on to a payment network. If not specified, the initiator and type parameters are set to default values. |
initiator | string | Applicable values:merchant (default) - the payment is initiated by the merchant, no action by the customer is required (for example a taxi ride cost is charged automatically from the customer's card after the ride is finished);customer - the payment is initiated by the customer, the payment confirmation by the customer is required (for example the customer pays a bill with the saved card). |
type | string | Used only if additional_data.card_on_file.initiator is set to merchant . delayed_charge (default) - delayed charge (for example for the additionally rendered service);increment - you should charge an extra amount (for example in case of the upsale);resubmission - you re-submit a transaction request due to the payment failure (for example no money on the card);reauthorization - you want to renew the authorization (for example to keep money reserved on the card for future charges);no_show - you want to charge the card when the customer didn't use the product or service (for example no visit to a hotel). |
browser | object | A section of client browser details. Section parameters are required for the 3-D Secure 2.0 flow only. |
accept_header | integer | A value of Accept request HTTP header sent by the cardholder browser. |
screen_width | integer | Screen width in pixels. Equals the screen.width parameter of JavaScript. |
screen_height | integer | Screen height in pixels. Equals the screen.height parameter of JavaScript. |
screen_color_depth | integer | Screen color depth in bits per pixel. Equals the screen.colorDepth parameter of JavaScript. Applicable values are:1 - 1 bit4 - 4 bits8 - 8 bits15 - 15 bits16 - 16 bits24 - 24 bits32 - 32 bits48 - 48 bits |
window_width | integer | Browser window width in pixels. Equals the document.body.clientWidth parameter of JavaScript. |
window_height | integer | Browser window height in pixels. Equals the document.body.clientHeight parameter of JavaScript. |
language | string | Language of the navigator. Equals the navigator.language parameter of JavaScript. |
java_enabled | boolean | Indicates if the browser is Java-enabled or not. Equals the navigator.javaEnabled() parameter of JavaScript. |
user_agent | string | User agent string for the browser. Equals the navigator.userAgent parameter of JavaScript. |
time_zone | integer | Time zone difference, in minutes, from the current locale (host system settings) to UTC. Equals the new Date().getTimezoneOffset() parameter of JavaScript. |
time_zone_name | string | A time zone name. Equals the Intl.DateTimeFormat().resolvedOptions().timeZone parameter of JavaScript. |
customer * conditionally required |
object | A section of the customer information. Contact the Tech Support Team to check what section parameters are required. |
ip | string | An IP address of the customer placing an order. |
string | An email of the customer placing an order. | |
device_id | string | A device ID (desktop, smartphone, etc.) of the customer placing an order. |
birth_date | string | The customer's date of birth in the ISO 8601 format YYYY-MM-DD . |
taxpayer_id | string | The customer's taxpayer ID. |
billing_address | object | A section of parameters related to the customer's billing address. Contact the Tech Support Team to check if your acquirer requires any of the section parameters. |
first_name * conditionally required |
string | The customer's first name. The maximal length is 30 characters. |
last_name * conditionally required |
string | The customer's last name. The maximal length is 30 characters. |
country * conditionally required |
string | The customer's billing country in ISO 3166-1 Alpha-2 format. |
city * conditionally required |
string | The customer's billing city. The maximal length is 60 characters. |
state * conditionally required |
string | The customer's two-letter billing state only if the billing address country is US or CA . |
zip | string | The customer's billing ZIP or postal code. If the country is US , the zip format must be NNNNN or NNNNN-NNNN. |
address * conditionally required |
string | The customer's billing address. The maximal length is 255 characters. |
phone * conditionally required |
string | The customer's phone number. The maximal length is 100 characters. |
travel | object | Section with travel related data. |
airline | object | Section for airline ticket addendum data. |
agency_code | string | IATA agency code (for example 03 ). |
agency_name | string | Agency name that sold the ticket (for example Coral travel ). |
ticket_number | string | 14-digit ticket number. Contains 3-digit ticketing code, 4-digit form number, 6-digit serial number, and the check digit (for example 390 5241 025377 1 ). |
booking_number | string | Booking code (for example DKZVUA ). |
restricted_ticked_indicator | string | Information on ticket returns. 0 - when the ticket can be returned. 1 - when the ticket may not be returned. |
legs | array | Array of travel legs. Every leg consists of: |
airline_code | string | 2-letter IATA code (for example B2 ). |
stop_over_code | string | IATA stop-over code. If a traveler stays in the originating city more than 24h, then set the field value to O or leave it empty. If the originating airport is a transit airport, then set the field value to X . |
flight_number | string | Flight number (for example A3 971 ). |
departure_date_time | string | Departure date and time (for example 2014-05-26T05:15:00 ). |
arrival_date_time | string | Arrival date and time (for example, 2014-05-26T07:30:00 ). |
originating_country | string | Country of origin (RU ). |
originating_city | string | City of origin (for example Moscow ) |
originating_airport_code | string | 3-letter IATA code of the airport of origin (for example DME ). |
destination_country | string | Country that the traveler goes to (for example Greece ). |
destination_city | string | City that the traveler goes to (for example Athens ). |
destination_airport_code | string | 3-letter IATA code of the airport that the traveler goes to (for example ATH ). |
coupon | string | Coupon number if applicable. |
class | string | Class flight, 1-letter IATA code (for example C ). |
passengers | array | List of passengers where every list item consists of |
first_name | string | Passenger's first name (for example KONSTANTIN ). |
last_name | string | Passenger's last name (for example IVANOV ). |
Example of the request
{
"request": {
"amount": 100,
"currency": "USD",
"description": "Test transaction",
"tracking_id": "tracking_id_000",
"credit_card": {
"number": "5204240000015003",
"verification_value": "123",
"holder": "John Doe",
"exp_month": "10",
"exp_year": 2026
},
"additional_data": {
"browser": {
"screen_width": 1920,
"screen_height": 1080,
"screen_color_depth": 24,
"language": "en",
"java_enabled": false,
"user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36",
"time_zone": -180,
"time_zone_name": "Europe/Helskinki",
"accept_header": "*/*",
"window_height": 667,
"window_width": 600
}
},
"three_d_secure": {
"advanced": false
},
"test": true
}
}
Response
The parameters of the response correspond to the parameters of the charge request and additionally specify the following:
Parameter | Type | Description |
---|---|---|
type * required |
string | A transaction type, set to charge . |
parent_uid * required |
string | Transaction ID. Same as uid , if the general request was modified to the payment, or stands for the capture request identifier. |
redirect_url * required |
string | A URL of the page to finalize the transaction. If the status parameter is set to incomplete , redirect the customer to this URL. It runs the 3-D Secure verification of the cardholder. |
Info
At the moment, if you accept payments on the UnonaPay widget and indicate charge
as the transaction_type
parameter value, you might not receive values for the rrn
or bank_code
parameters.
Example of the response to the charge request
{
"uid": "c74e1b00-9b94-4682-82c3-60167ce64841",
"parent_uid": "c74e1b00-9b94-4682-82c3-60167ce64841",
"status": "successful",
"amount": 100,
"currency": "USD",
"description": "Test transaction ütf",
"type": "charge",
"payment_method_type": "credit_card",
"tracking_id": "tracking_id_000",
"message": "Successfully processed",
"test": true,
"created_at": "2024-06-19T08:53:41.211Z",
"updated_at": "2024-06-19T08:53:46.217Z",
"paid_at": "2024-06-19T08:53:46.149Z",
"expired_at": null,
"closed_at": null,
"settled_at": null,
"manually_corrected_at": null,
"language": "en",
"redirect_url": "https://gateway.unonapay.com/process/c74e1b00-9b94-4682-82c3-60167ce64841",
"credit_card": {
"holder": "John Doe",
"stamp": "a282993adc1299dacc79248e77e04c2995f79fcc9f82f408bec59ba20ff55739",
"brand": "master",
"last_4": "5003",
"first_1": "5",
"bin": "520424",
"bin_8": "52042400",
"issuer_country": null,
"issuer_name": null,
"product": null,
"exp_month": 10,
"exp_year": 2026,
"token_provider": null,
"token": null
},
"status_code": null,
"gateway": {
"iframe": true
},
"mute_notifications": null,
"id": "c74e1b00-9b94-4682-82c3-60167ce64841",
"additional_data": {},
"links": {
"receipt_url": "https://online.unonapay.com/customer/transactions/c74e1b00-9b94-4682-82c3-60167ce64841/33724a6fe94fe937575c6ed18d2ab8abdc34732df17e51be6da88e9b37356101?language=en"
},
"code": "S.0000",
"friendly_message": "The operation is successful.",
"smart_routing_verification": {
"status": "successful"
},
"charge": {
"auth_code": "654321",
"bank_code": "05",
"rrn": "999",
"ref_id": "777888",
"message": "Payment was approved",
"amount": 100,
"currency": "USD",
"billing_descriptor": "test descriptor",
"gateway_id": 3483,
"status": "successful"
},
"avs_cvc_verification": {
"avs_verification": {
"result_code": "1"
},
"cvc_verification": {
"result_code": "1"
}
},
"customer": {
"ip": null,
"email": null,
"device_id": null,
"birth_date": null,
"taxpayer_id": null,
"external_id": null,
"first_name": null,
"last_name": null,
"address": null,
"country": null,
"city": null,
"zip": null,
"state": null,
"phone": null
},
"billing_address": {
"first_name": null,
"last_name": null,
"address": null,
"country": null,
"city": null,
"zip": null,
"state": null,
"phone": null
}
}