Create a direct payment

Request

Header Params

Content-Type

string

required

Example:

application/x-www-form-urlencoded

Body Params application/json

merchant_id

string

required

Merchant Code or Merchant ID or Merchant Number

<= 7 characters

Example:

701001

account_id

string

required

Subaccount Code or Subaccount ID or Gateway Number

<= 10 characters

Example:

701001010

order_no

string

required

Order number defined by merchant

<= 50 characters

Example:

1726891254563

currency

string

required

Order Currency Code. Please refer to ISO 4217

<= 3 characters

Example:

USD

amount

string

required

The sum of the amounts of all items in an order; Value can be digits only. Please refer to ISO 4217 for decimal values of each currency

amount = item_total + shipping + handing + tax_total + insurance - shiopping_discount - discount

<= 15 characters

Example:

10.36

item_total

string

optional

The subtotal for all items can not be a negative number.

<= 15 characters

Example:

10.00

shipping

string

optional

The shipping fee for all items within the items parameter can not be a negative number.

<= 15 characters

Example:

1.00

handling

string

optional

The handling fee for all items within the items parameter can not be a negative number.

<= 15 characters

Example:

1.00

tax_total

string

optional

The total tax for all items within the items parameter can not be a negative number.

<= 15 characters

Example:

1.00

insurance

string

optional

The insurance fee for all items within the items parameter can not be a negative number.

<= 15 characters

Example:

1.00

shipping_discount

string

optional

The shipping discount for all items within the items parameter can not be a negative number.

<= 15 characters

Example:

1.00

discount

string

optional

The discount for all items within the items parameter can not be a negative number.

<= 15 characters

Example:

1.00

website

string

required

The domain of shopping website.

<= 2000 characters

Example:

website.com

items

string

required

Items information, including item name, ID, unit price, and quantity Please refer to Items Information

<= 5000 characters

Example:

huawei#,#NUM1#,#230.00#,#1#;#Test2#,#NUM2#,#290.00#,#2

note

string

optional

Additional information or comments for an order, customized by merchant.

<= 1000 characters

Example:

shopper_id

string

required

The ID which is allocated or created by Merchant to specify the shopper

<= 64 characters

Example:

apidog1

shopper_email

string

required

Shopper’s email address

<= 100 characters

Example:

apidog@gmail.com

shopper_ip

string

required

Shopper's IP address

<= 50 characters

Example:

219.78.45.63

shopper_phone

string

optional

Shopper's phone number, CODI Required

<= 50 characters

Example:

13012345678

shopper_level

string

optional

Shopper tiers defined by merchants

<= 50 characters

Example:

open3d

string

optional

Open the 3DS
do3DS: try 3D
no3DS: non 3d

<= 10 characters

Example:

do3DS

token_flag

string

optional

To indicate whether or not to tokenize the card information
YES: Tokenize the card information
NO: Do Not tokenize the card information
This parameter is required when Token is used

<= 10 characters

Example:

token_id

string

optional

Required when tokenization is used
Note: The expiration date of token_id is the same as the card expiration date; Once a token is expired new token need to be created during a new payment process

<= 50 characters

Example:

card

string

required

Card number used to make the payment
This parameter can be Null/Default if parameter {token_id} is used

<= 20 characters

Example:

4242424242424242

expiration_month

string

required

Month in card expiration date. i.e. 05
This parameter can be Null/Default if parameter {token_id} is used

<= 2 characters

Example:

expiration_year

string

required

Year in card expiration date. i.e. 2020
This parameter can be Null/Default if parameter {token_id} is used

<= 4 characters

Example:

2030

security_code

string

required

Card security code: the 3-4 digits on the back of the card
This parameter can be Null/Default if parameter {token_id} is used

<= 4 characters

Example:

321

first_name

string

required

First name of cardholder

<= 100 characters

Example:

Milton

last_name

string

required

Last name of cardholder

<= 100 characters

Example:

Braganza

notify_url

string

required

The merchant customized URL address where the payment notification will be sent to

<= 500 characters

Example:

{{webUrl}}/v1/pages/NotifyResult.jsp

document

string

optional

User’s personal identification number. Required by some acquirers, example: Dlocal

<= 50 characters

Example:

birth_date

string

optional

User’s birthdate (DD-MM-YYYY).

<= 10 characters

Example:

02-02-1920

billing_country

string

optional

2 digits ISO Country Code; Refer to ISO 3166-2 country code
This parameter is required for tangible goods

<= 2 characters

Example:

billing_state

string

optional

State in the billing address
This parameter is required for tangible goods and when the country is United States or Canada

<= 100 characters

Example:

billing_city

string

optional

City in the billing address
This parameter is required for tangible goods

<= 100 characters

Example:

Xiamen

billing_address

string

optional

Street address in the billing address
This parameter is required for tangible goods

<= 300 characters

Example:

3610 Brighton Circle Road

billing_postal_code

string

optional

Postal code in the billing address
This parameter is required for tangible goods

<= 100 characters

Example:

56376

string

optional

Shopper's operational system

<= 100 characters

Example:

Win10

browser

string

optional

Shopper's browser

<= 2000 characters

Example:

Mozilla/5.0 (Windows NT 10.0; WOW64) …

browser_lang

string

optional

Shopper's browser language

<= 300 characters

Example:

en-US

time_zone

string

optional

Shopper's time zone

<= 50 characters

Example:

resolution

string

optional

Shopper's screen resolution Example:1920x1080

<= 50 characters

Example:

1920x1080

cookie_new

string

optional

Values of new cookie
Example:
billing_country=US&shopper_email=test@test.com&time_zone=8&order_no=ter56789&lang=en_US&IP=127.0.0.1&$$billing_country=US&shopper_email=test@test.com&time_zone=8&order_no=ter1234&lang=en_US&shopper_ip=127.0.0.1&

<= 1000 characters

Example:

billing_country=US&shopper_email=test@ company.com&time_zone=....

cookie_old

string

optional

Values of old cookie
Example:
billing_country=US&shopper_email=test@test.com&time_zone=8&order_no=ter1234&lang=en_US&shopper_ip=127.0.0.1&

<= 1000 characters

Example:

billing_country=US&shopper_email=test@ company.com&time_zone=....

challenge_window_size

string

optional

Challenge window size
'01': ['250px', '400px']
'02': ['390px', '400px'] - The default window size
'03': ['500px', '600px']
'04': ['600px', '400px']
'05': ['100%', '100%']

<= 2 characters

Example:

session_id

string

optional

Session ID

<= 50 characters

Example:

delivery_firstname

string

optional

First name of consignee

<= 100 characters

Example:

delivery_lastname

string

optional

Last name of consignee

<= 100 characters

Example:

Han

delivery_country

string

optional

2 digits ISO Country Code of the country in the delivery address (i.e. United States should be in the form of US)

<= 100 characters

Example:

delivery_state

string

optional

State in the delivery address This parameter is required for tangible goods and when the country is United States or Canada

<= 100 characters

Example:

delivery_city

string

optional

City in the delivery address

<= 100 characters

Example:

Xiamen

delivery_address

string

optional

Street address of consignee

<= 300 characters

Example:

3610 Brighton Circle Road

delivery_postal_code

string

optional

Postal or zip code in the delivery address
This parameter is required for tangible goods and when the country is United States or Canada

<= 100 characters

Example:

56376

custom

string

optional

Each custom parameter is separated by semicolons (;), and supports up to 5 custom parameters. The value of the parameter cannot contain semicolons and the length is less then 500 digits.
Example:
custom1;custom2;custom3;custom4;custom5

<= 2500 characters

Example:

installments

string

optional

Number of installments.

<= 2 characters

Example:

installments_id

string

optional

The installments id.

<= 50 characters

Example:

device_fingerprint

string

optional

Device fingerprint

<= 200 characters

Example:

encryption_data

string

required

Digital signatures information
encryption_data=sha256(merchant_id + account_id +order_no + currency +amount + first_name + last_name + card + expiration_year + expiration_month+ security_code + shopper_email + sign_key);
All encryption parameters need to remove spaces before encryption.

<= 64 characters

Example:

platform_source

string

optional

Name of ecommerce platform that your website used.
Acceptable Value: Magento, Shopify, Shoplazza, Shopyy, Shopline, WooCommerce, Zencart, SAAS

<= 30 characters

Example:

Shopify

device_type

string

optional

Devices used when payment is processed/made. Acceptable Value: PC, Mobile

<= 20 characters

Example:

order_type

string

optional

Platform order was made through. Can be one of WEB, PHONE, DYNAMIC_PHONE, MOBILE, MOBILE_IN_STORE, IOS, ANDROID, WAP, STORE, MERCHANT_EMPLOYEE, MAIL_ORDER, AUTOMATIC_RENEWAL_OR_INSTALLMENT_PAYMENT, MERCHANT_INITIATED, UNKNOWN, POS, API_ONLY, PERSONAL_POS, PHONE_LINK

<= 50 characters

Example:

WEB

checkout_time

number

optional

The time when the buyer completed the checkout process in the merchant website in SECONDS since unix epoch (Jan 1, 1970).

Example:

1415273168

user_agent

string

optional

The user-agent string sent by the browser helps identify the browser type (e.g., Chrome, Firefox, Safari) and its version, as well as the operating system being used (e.g., Windows, macOS, iOS, Android)

<= 2000 characters

Example:

Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.73 Safari/537.36

forter_token_cookie

string

optional

Forter token cookie from request headers

<= 128 characters

Example:

cart_items

array [object {1}]

optional

A list of all items purchased and shipping details

basic_item_data

object

optional

General data regarding item such as name, price, etc

account_owner

array [object {9}]

optional

The customer's basic information

first_name

string

optional

Account holder's first name

<= 75 characters

last_name

string

optional

Account holder's last name

<= 75 characters

string

optional

Account holder's primary Email address

<= 256 characters

account_id

string

optional

Customer's account UID in merchant 's site (leave empty if guest)

<= 100 characters

created

number

optional

Account creation date in seconds since unix epoch (UTC, Jan 1, 1970)

past_orders_count

number

optional

Count of all successfully fulfilled orders made by account. Use -1 if unknown and during partial updates.

past_orders_sum

number

optional

Sum in USD of all successfully fulfilled orders made by account. Use -1 if unknown and during partial updates

lastLogin_ip

string

optional

IP address used by the account owner at the time of last login

<= 50 characters

registration_ip

string

optional

IP address used by the account owner at the time of registration

<= 50 characters

total_discount

array [object {2}]

optional

Discount that was given to the customer

coupon_code_used

string

optional

Coupon code used

<= 15 characters

discount_type

string

optional

Discount type: COUPON

<= 25 characters

additional_information

array [object {1}]

optional

Additional information not described in the documentation

mpi_info

object

optional

Details for MPI information, 3DS verification result if external 3DS is used

price_id

string

optional

The price id the customer is subscribed to

<= 50 characters

quote_id

string

optional

The ID of the quote

<= 50 characters

quote_price

string

optional

The price of the quote

<= 15 characters

Example

{
  "merchant_id": "701001",
  "account_id": "701001010",
  "order_no": "1726891254563",
  "currency": "USD",
  "amount": "10.36",
  "item_total": "10.00",
  "shipping": "1.00",
  "handling": "1.00",
  "tax_total": "1.00",
  "insurance": "1.00",
  "shipping_discount": "1.00",
  "discount": "1.00",
  "website": "website.com",
  "items": "huawei#,#NUM1#,#230.00#,#1#;#Test2#,#NUM2#,#290.00#,#2",
  "note": "",
  "shopper_id": "apidog1",
  "shopper_email": "apidog@gmail.com",
  "shopper_ip": "219.78.45.63",
  "shopper_phone": "13012345678",
  "shopper_level": "1",
  "open3d": "do3DS",
  "token_flag": "NO",
  "token_id": "",
  "card": "4242424242424242",
  "expiration_month": "12",
  "expiration_year": "2030",
  "security_code": "321",
  "first_name": "Milton",
  "last_name": "Braganza",
  "notify_url": "{{webUrl}}/v1/pages/NotifyResult.jsp",
  "document": "",
  "birth_date": "02-02-1920",
  "billing_country": "CN",
  "billing_state": "FJ",
  "billing_city": "Xiamen",
  "billing_address": "3610  Brighton Circle Road",
  "billing_postal_code": "56376",
  "os": "Win10",
  "browser": "Mozilla/5.0 (Windows NT 10.0; WOW64) …",
  "browser_lang": "en-US",
  "time_zone": "8",
  "resolution": "1920x1080",
  "cookie_new": "billing_country=US&shopper_email=test@ company.com&time_zone=.... ",
  "cookie_old": "billing_country=US&shopper_email=test@ company.com&time_zone=.... ",
  "challenge_window_size": "01",
  "session_id": "",
  "delivery_firstname": "Li",
  "delivery_lastname": "Han",
  "delivery_country": "CN",
  "delivery_state": "FJ",
  "delivery_city": "Xiamen",
  "delivery_address": "3610  Brighton Circle Road",
  "delivery_postal_code": "56376",
  "custom": "",
  "installments": "",
  "installments_id": "",
  "device_fingerprint": "",
  "encryption_data": "{{sign}}",
  "platform_source": "Shopify",
  "device_type": "PC",
  "order_type": "WEB",
  "checkout_time": 1415273168,
  "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.73 Safari/537.36",
  "forter_token_cookie": "",
  "cart_items": [
    {
      "basic_item_data": {
        "name": "string",
        "quantity": "string",
        "type": "string",
        "price": {
          "amount_usd": 0,
          "amount_local_currency": 0,
          "currency": "str"
        },
        "category": "string",
        "productId": "string"
      }
    }
  ],
  "account_owner": [
    {
      "first_name": "string",
      "last_name": "string",
      "email": "string",
      "account_id": "string",
      "created": 0,
      "past_orders_count": 0,
      "past_orders_sum": 0,
      "lastLogin_ip": "string",
      "registration_ip": "string"
    }
  ],
  "total_discount": [
    {
      "coupon_code_used": "string",
      "discount_type": "string"
    }
  ],
  "additional_information": [
    {
      "mpi_info": {
        "eci": "st",
        "cavv": "string",
        "xid": "string",
        "dsTransID": "string"
      }
    }
  ],
  "price_id": "string",
  "quote_id": "string",
  "quote_price": "string"
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200OK

application/xml

Body

merchant_id

string

required

account_id

string

required

order_no

string

required

amount

string

required

currency

string

required

transaction_id

string

required

card

string

required

order_status

string

required

result_info

string

required

contract_name

string

required

recurring_id

string

required

recurring_deduction_period

string

required

recurring_deduction_time

string

required

encryption_data

string

required

note

string

required

connector

string

required

Example

<?xml version="1.0" encoding="UTF-8"?>
<respon>
    <merchant_id>701001</merchant_id>
    <account_id>701001021</account_id>
    <order_no>1726206945985</order_no>
    <amount>10.36</amount>
    <currency>USD</currency>
    <transaction_id>Ca267324866591</transaction_id>
    <card>400000***1091</card>
    <order_status>1</order_status>
    <result_info>0000:Success</result_info>
    <encryption_data>E72300476702EBD9DFF06B51B941BB570C059C9EB1F794E60DD4F78D7A4EBCEF</encryption_data>
    <note></note>
    <connector>AIGLOBALPAY</connector>
</respon>

🟠404Record not found

🟠400Invalid input