Create a APM payment

Alternative Payment Method
When the payment method is Alternative Payment Method, the issuer_url of the corresponding payment method will be returned, you need to request the issuer_url again and redirect to the payment page of the issuer to make payment.

Request

Header Params

Content-Type

string

required

Example:

application/x-www-form-urlencoded

Body Params application/json

payment_method

string

required

payment method type. i.e. PAYPAL, MercadoPago, TransbankOneClick, etc

<= 50 characters

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:

first_name

string

required

First name of cardholder

<= 100 characters

Example:

Milton

last_name

string

required

Last name of cardholder

<= 100 characters

Example:

Braganza

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=....

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_district_name

string

optional

Distict name in the delivery address
This parameter is required for Boletos payment in Brazil only.

<= 50 characters

delivery_street_name

string

optional

Street number in the delivery address
This parameter is required for Boletos payment in Brazil only.

<= 50 characters

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

return_url

string

optional

Real-time return URL defined by merchant for complete payment

<= 500 characters

notify_url

string

optional

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

<= 500 characters

Example:

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

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:

device_fingerprint

string

optional

Device fingerprint

<= 200 characters

Example:

encryption_data

string

required

Digital signatures information
encryption_data=sha256(merchant_id + account_id +payment_method +order_no + currency +amount + first_name + last_name + 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:

person

object

required

Person, some of the payment methods for LATAM are required

document_number

string

required

client’s document number

<= 30 characters

document_type

string

optional

type of the document number specified above. Refer to the domain table below for the list of accepted values.

<= 30 characters

social_name

string

optional

client's social name

<= 100 characters

string

optional

client's e - mail address

<= 100 characters

phone_country_code

string

optional

international country phone code (2 digits)

<= 2 characters

phone_area_code

string

optional

internal country area code

<= 20 characters

phone_number

string

optional

client's phone number

<= 50 characters

birth_date

string

optional

client's date of birth(yyyy - mm - dd format)

<= 10 characters

net_monthly_average_income

string

optional

client's monthly average income

<= 10 characters

address_street

string

optional

client's street name

<= 100 characters

address_number

string

optional

client's street number

<= 30 characters

address_complement

string

optional

e.g.: apartment number

<= 100 characters

address_postal_code

string

optional

postal/zip code

<= 100 characters

address_city

string

optional

city of residence

<= 100 characters

address_state

string

optional

state of residence

<= 100 characters

address_country

string

optional

An ISO 3166-1 alpha-2 country code of the country of residence

<= 2 characters

fiscal_country

string

optional

An ISO 3166-1 alpha-2 country code of the customer’s tax country

<= 2 characters

documents

object

optional

An array of documents related to the user. Refer to the upload section for more information

bank_code

string

optional

Please refer to Appendix: Bank Code

<= 50 characters

color_depth

string

optional

Get the color depth of the screen of the client, which is obtained from screen.colorDepth.

<= 50 characters

Example

{
    "payment_method": "string",
    "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",
    "first_name": "Milton",
    "last_name": "Braganza",
    "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=.... ",
    "delivery_firstname": "Li",
    "delivery_lastname": "Han",
    "delivery_country": "CN",
    "delivery_state": "FJ",
    "delivery_city": "Xiamen",
    "delivery_district_name": "string",
    "delivery_street_name": "string",
    "delivery_address": "3610  Brighton Circle Road",
    "delivery_postal_code": "56376",
    "return_url": "string",
    "notify_url": "{{webUrl}}/v1/pages/NotifyResult.jsp",
    "custom": "",
    "device_fingerprint": "",
    "encryption_data": "{{sign}}",
    "platform_source": "Shopify",
    "device_type": "PC",
    "person": {
        "document_number": "string",
        "document_type": "string",
        "social_name": "string",
        "email": "string",
        "phone_country_code": "st",
        "phone_area_code": "string",
        "phone_number": "string",
        "birth_date": "string",
        "net_monthly_average_income": "string",
        "address_street": "string",
        "address_number": "string",
        "address_complement": "string",
        "address_postal_code": "string",
        "address_city": "string",
        "address_state": "string",
        "address_country": "st",
        "fiscal_country": "st",
        "documents": {
            "file_type": "string",
            "file_data": "string",
            "file_url": "string",
            "labels": {
                "person_bank_account_id": "string",
                "bank_account": {
                    "account_type": "string",
                    "account_number": "string",
                    "branch_number": "string",
                    "owner_document_number": "string",
                    "owner_name": "string",
                    "branch_country": "st",
                    "currency": "str",
                    "bank": {
                        "code": "string",
                        "name": "string"
                    }
                }
            }
        }
    },
    "bank_code": "string",
    "color_depth": "string"
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200OK

application/xml

Returns
The response is in XML format. Merchant needs to parse the XML response before obtain the payment result.

Body

merchant_id

string

optional

Merchant Code or Merchant ID or Merchant Number

<= 5 characters

account_id

string

optional

Subaccount Code or Subaccount ID or Gateway Number

<= 8 characters

order_no

string

optional

Merchant Order Number (or Merchant Order ID) generated by Merchant

<= 50 characters

amount

string

optional

The sum of the amounts of all items in an order; Value can be digits only
please refer to Appendix: Transaction Currency for decimal values of each currency

<= 15 characters

currency

string

optional

Transaction Currency
Please refer to Appendix: Transaction Currency

<= 3 characters

issuer_url

string

optional

issuer url

<= 500 characters

Example

<?xml version="1.0" encoding="UTF-8"?>
    <respon>
    <merchant_id>10001001</merchant_id>
    <account_id>10001001001</account_id>
    <order_no>112343455</order_no>
    <amount>188.58</amount>
    <currency>MXN</currency>
    <issuer_url>https://sandbox.dlocal.com/collect/pay/pay/M-e55f92cb-acc9-47f2-aa60-e99819180b4c?xtid=CATH-ST-1639120320-214722374</issuer_url>
</respon>

🟠404Record not found

🟠400Invalid input

🟢200OK