Payment

A transaction made by the user within a payment session is identified as payment..

Refund

The refund endpoint allows to refund an approved transaction. See more in Refund

POST/api/reverse

It allows you to perform basic preauthorization operations such as checkout, reauthorization, (Does not apply to Puerto Rico) on the other hand it also allows you to reverse an approved payment with the internal reference code reverse.

Request

Structure that allows for preauthorization requests such as checkout, reauthorization and reverse

Name
auth
Type
Authentication
is Required
REQUIRED
Description
Site authentication. See more in Authentication
Name
login
Type
string
is optional
Description
Site identifier.
Min length:1
Name
tranKey
Type
string
is optional
Description
Generated tranKey credential. See more in Authentication
Min length:1
Name
nonce
Type
string
is optional
Description
Random value for each Base64 encoded request.
Min length:1
Name
seed
Type
string
is optional
Description
Current date, which is generated in ISO 8601 format.
Min length:1
Name
action
Type
string
is Required
REQUIRED
Description
Type of operation to perform on the transaction

reverse to reverse a transaction. reauthorization to modify a checkin transaction. checkout to close and collect a checkin transaction.
Allowed values:checkoutreauthorizationreverse
Example:checkout
Name
internalReference
Type
integer
is Required
REQUIRED
Description
Unique internal reference of the transaction

e.g.: 543423
Name
amount
Type
Amount
is optional
Description
Information on the amount to be collected
Name
currency
Type
string
is optional
Description
Alphabetical code of the currency to be used (ISO 4217 alpha code) e.g.: USD
Example:COP
Name
total
Type
number
is optional
Description
Total value in the indicated base currency
e.g.: 1000 equals one thousand dollars
Example:2000
Name
taxes
Type
array[Taxes]
is optional
Description
Structure to define taxes in the payment process.
Name
kind
Type
string
is optional
Description
Tax type identifier

One of: valueAddedTax exciseDuty ice airportTax stateTax reducedStateTax municipalTax.
Allowed values:valueAddedTaxexciseDutyiceairportTaxstateTaxreducedStateTaxmunicipalTax
Example:valueAddedTax
Name
amount
Type
number
is optional
Description
Full amount of tax
e.g.: 200
Name
base
Type
number
is optional
Description
Base amount on which the tax is calculated
e.g.: 1000
Name
details
Type
array[Details]
is optional
Description
Structure to define additional details of the amount in the payment process.
Name
kind
Type
string
is optional
Description
Detail Type Identifier. One of: discount additional vatDevolutionBase shipping handlingFee insurance giftWrap subtotal fee tip airline interests
Allowed values:discountadditionalvatDevolutionBaseshippinghandlingFeeinsurancegiftWrapsubtotalfeetipairlineinterests
Example:discount
Name
amount
Type
number
is optional
Description
Total amount of detail

e.g.: 200

Request

POST

/api/transaction

curl -X "POST" https://checkout-test.placetopay.com/api/transaction \
    -H "Content-Type: application/json" \
    -d "{
        "auth": {
            "login": "c51ce410c124a10e0db5e4b97fc2af39",
            "tranKey": "VQOcRcVH2DfL6Y4B4SaK6yhoH/VOUveZ3xT16OQnvxE=",
            "nonce": "NjE0OWVkODgwYjNhNw==",
            "seed": "2021-09-21T09:34:48-05:00"
        },
        "internalReference": 640,
        "amount": {
            "currency": "USD",
            "total": "500"
        },
        "action": "checkout"
    }"

Response

Name
reference
Type
string
is Required
REQUIRED
Description
Unique payment reference, consisting of up to 32 alphanumeric characters and permitted symbols e.g.: PAYMENT_0001_ABC, Venta_1234-ABCD#2024/03/15$500, Ord: 1001/2023
Example:12345
Name
description
Type
string
is Required
REQUIRED
Description
Description of the process to be performed, allowing up to 250 alphanumeric, accented characters, and common symbols e.g.: Cita con el Dr. Pérez a las 10:00 am. 5/12/2024, por $100.00
Example:Consumo mes de Mayo
Name
amount
Type
Amount
is Required
REQUIRED
Description
Information on the amount to be collected
Name
currency
Type
string
is optional
Description
Alphabetical code of the currency to be used (ISO 4217 alpha code) e.g.: USD
Example:COP
Name
total
Type
number
is optional
Description
Total value in the indicated base currency
e.g.: 1000 equals one thousand dollars
Example:2000
Name
taxes
Type
array[Taxes]
is optional
Description
Structure to define taxes in the payment process.
Name
kind
Type
string
is optional
Description
Tax type identifier

One of: valueAddedTax exciseDuty ice airportTax stateTax reducedStateTax municipalTax.
Allowed values:valueAddedTaxexciseDutyiceairportTaxstateTaxreducedStateTaxmunicipalTax
Example:valueAddedTax
Name
amount
Type
number
is optional
Description
Full amount of tax
e.g.: 200
Name
base
Type
number
is optional
Description
Base amount on which the tax is calculated
e.g.: 1000
Name
details
Type
array[Details]
is optional
Description
Structure to define additional details of the amount in the payment process.
Name
kind
Type
string
is optional
Description
Detail Type Identifier. One of: discount additional vatDevolutionBase shipping handlingFee insurance giftWrap subtotal fee tip airline interests
Allowed values:discountadditionalvatDevolutionBaseshippinghandlingFeeinsurancegiftWrapsubtotalfeetipairlineinterests
Example:discount
Name
amount
Type
number
is optional
Description
Total amount of detail

e.g.: 200
Name
allowPartial
Type
boolean
is optional
Description
Defines if the amount to be charged can be paid in several transactions. When set to true the user will be able to complete the payment in multiple transactions.
Default value:false
Name
shipping
Type
Person
is optional
Description
Structure to relate shipping information.
Name
document
Type
string
is optional
Description
Identification document

e.g.: 1017111222
Example:1122334455
Min length:1
Name
documentType
Type
string
is optional
Description
Document type identifier. View options in Document Types

e.g.: CC for "Cédula de Ciudadanía" in Colombia.
Example:CC
Min length:1
Name
name
Type
string
is optional
Description
Name of the person or company

e.g.: Juan José
Example:John
Min length:1
Name
surname
Type
string
is optional
Description
Last name of the person. Does not apply when the type of document corresponds to that of a company

e.g.: Peréz Pinzon
Example:Doe
Min length:1
Name
company
Type
string
is optional
Description
Name of the company to which the person belongs

e.g.: Placetopay
Example:Evertec
Name
email
Type
string
is optional
Description
Email of the user or company

e.g.: [email protected]
Example:[email protected]
Min length:1
Name
mobile
Type
string
is optional
Description
User or company phone number

e.g.: +573214445566
Example:+573214445566
Min length:1
Name
address
Type
object
is optional
Description
Structure to attach address or address information
Name
country
Type
string
is optional
Description
The country in which the address is located. ISO 3166-1 alpha-2 code.
Example:CO
Max length:2
Min length:2
Name
state
Type
string
is optional
Description
Domicile department

e.g.: Antioquia
Example:Antioquia
Min length:1
Name
city
Type
string
is optional
Description
City of residence

e.g.: Medellín
Example:Medellín
Min length:1
Name
postalCode
Type
string
is optional
Description
Postal code of the address

e.g.: 050012
Example:55555
Min length:1
Name
street
Type
string
is optional
Description
Home address

e.g.: Calle 12 #33a-12, Apto 101
Example:Calle falsa 123
Min length:1
Name
phone
Type
string
is optional
Description
Home phone number

e.g.: +573214445566
Example:+573111111111
Min length:1
Name
items
Type
array[Item]
is optional
Description
Structure to relate products or items in the process.
Name
sku
Type
string
is optional
Description
Item SKU.
e.g.: SKU-12345
Example:SKU-12345
Name
name
Type
string
is optional
Description
Article name.
e.g.: Manta de lana
Example:product_1
Min length:1
Name
category
Type
string
is optional
Description
Article category. One of: digital physical
Allowed values:digitalphysical
Example:physical
Min length:1
Name
qty
Type
number
is optional
Description
Number of articles of this type.
e.g.: 23
Example:1
Name
price
Type
number
is optional
Description
Total cost of the article.
e.g.: 1400
Example:1400
Name
tax
Type
number
is optional
Description
Item Tax Amount.
e.g.: 100
Name
fields
Type
array[NameValuePair]
is optional
Description
Structure to relate additional information in the process. See more in Additional Fields
Name
keyword
Type
string
is optional
Description
Identifier or index of the data to be attached.
e.g.: cmsInvoiceId
Example:1111
Min length:1
Name
value
Type
string|object|array|number|boolean
is optional
Description
Value of the data to be attached.
e.g.: ID_2233
Example:lastDigits
Min length:1
Name
displayOn
Type
string
is optional
Description
Indicates under what conditions the attached data is displayed. See more in Additional Fields

One of: none, payment, receipt, both, approved.
Example:none
Min length:1
Name
recurring
Type
object
is optional
Description
Structure to indicate the frequency of a recurring charge.
Name
periodicity
Type
string
is optional
Description
Frequency of collection
D Día, M Mes, Y Año
Allowed values:DMY
Example:D
Name
interval
Type
number
is optional
Description
Interval associated with the periodicity
e.g.: for 15 days.
Example:1
Max length:127
Min length:1
Name
nextPayment
Type
string
is optional
Description
next payment date
e.g.: 2019-08-24
Example:2019-08-24
Format:date
Name
maxPeriods
Type
number
is optional
Description
Maximum number of periods. Use -1 in case there is no limit
e.g.: 12 for a maximum of 12 charges
Example:1
Max length:32767
Min length:-1
Name
dueDate
Type
string
is optional
Description
Recurrence Due Date
e.g.: 2019-09-24
Example:2019-09-24
Format:date
Name
notificationUrl
Type
string
is optional
Description
URL in which the service will notify each time a charge is made
e.g.: https://merchant.com/notification
Example:https://checkout.placetopay.com
Name
subscribe
Type
boolean
is optional
Description
When true is sent, a subscription payment session is generated.

In the payment process, the user can choose whether or not to save his payment method to be used in future charges..
Default value:false
Name
dispersion
Type
array[DispersionDetail]
is optional
Description
When defined, a scatter payment session is generated. The generated payment can be divided into different destinations according to the given conditions.
Name
amount
Type
Amount
is optional
Description
I ride to "scatter" in this destination.
Name
currency
Type
string
is optional
Description
Alphabetical code of the currency to be used (ISO 4217 alpha code) e.g.: USD
Example:COP
Name
total
Type
number
is optional
Description
Total value in the indicated base currency
e.g.: 1000 equals one thousand dollars
Example:2000
Name
taxes
Type
array[Taxes]
is optional
Description
Structure to define taxes in the payment process.
Name
kind
Type
string
is optional
Description
Tax type identifier

One of: valueAddedTax exciseDuty ice airportTax stateTax reducedStateTax municipalTax.
Allowed values:valueAddedTaxexciseDutyiceairportTaxstateTaxreducedStateTaxmunicipalTax
Example:valueAddedTax
Name
amount
Type
number
is optional
Description
Full amount of tax
e.g.: 200
Name
base
Type
number
is optional
Description
Base amount on which the tax is calculated
e.g.: 1000
Name
details
Type
array[Details]
is optional
Description
Structure to define additional details of the amount in the payment process.
Name
kind
Type
string
is optional
Description
Detail Type Identifier. One of: discount additional vatDevolutionBase shipping handlingFee insurance giftWrap subtotal fee tip airline interests
Allowed values:discountadditionalvatDevolutionBaseshippinghandlingFeeinsurancegiftWrapsubtotalfeetipairlineinterests
Example:discount
Name
amount
Type
number
is optional
Description
Total amount of detail

e.g.: 200
Name
agreement
Type
string|number
is optional
Description
Id of the destination of this amount. It can be the id of a site.

e.g.: 122
Name
agreementType
Type
string
is optional
Description
Type of destination of this amount. MERCHANT for sites, AIRLINE for airlines.
Allowed values:MERCHANTAIRLINE
Example:MERCHANT
Name
modifiers
Type
array[Modifiers]
is optional
Description
Structure to define modifiers in the collection.

Applies to tax laws in specific countries.
Name
type
Type
string
is optional
Description
Modifier type identifier. Only FEDERAL_GOVERNMENT is currently supported.
Allowed values:FEDERAL_GOVERNMENT
Example:FEDERAL_GOVERNMENT
Name
code
Type
number
is optional
Description
Modifier code.

For FEDERAL_GOVERMENT represents the law number for discount. 17934 Gastronomic Services 18083 IMESI Brazil - Argentina 19210 Financial Inclusion 18910 Family Allowances 18999 Real Estate Reimbursement
Allowed values:1793418083192101891018999
Example:17934
Name
additional
Type
object
is optional
Description
Structure for appending information to the modifier
Name
invoice
Type
string
is optional
Description
Required when modifiers.[].type is FEDERAL_GOVERMENT. Indicates the invoice number.

e.g.: 123456789
Example:123456789
Max length:9
Name
processorFields
Type
array[NameValuePair]
is optional
Description
Structure that may vary over time depending on the information available for the means of payment. See more in Processor Fields
Name
keyword
Type
string
is optional
Description
Identifier or index of the data to be attached.
e.g.: cmsInvoiceId
Example:1111
Min length:1
Name
value
Type
string|object|array|number|boolean
is optional
Description
Value of the data to be attached.
e.g.: ID_2233
Example:lastDigits
Min length:1
Name
displayOn
Type
string
is optional
Description
Indicates under what conditions the attached data is displayed. See more in Additional Fields

One of: none, payment, receipt, both, approved.
Example:none
Min length:1

Response

{
    "reference": "12345",
    "description": "Prueba de pago",
    "amount": {
        "currency": "COP",
        "total": 2000,
        "taxes": [
        {
            "kind": "valueAddedTax",
            "amount": 1000,
            "base": 0
        }
        ],
        "details": [
        {
            "kind": "discount",
            "amount": 1000
        }
        ]
    },
    "allowPartial": false,
    "shipping": {
        "document": "1122334455",
        "documentType": "CC",
        "name": "John",
        "surname": "Doe",
        "company": "Evertec",
        "email": "[email protected]",
        "mobile": "+5731111111111",
        "address": {
            "street": "Calle falsa 123",
            "city": "Medellín",
            "state": "Poblado",
            "postalCode": "55555",
            "country": "CO",
            "phone": "+573111111111"
        }
    },
    "items": [
        {
        "sku": "12345",
        "name": "product_1",
        "category": "physical",
        "qty": "1",
        "price": 1000,
        "tax": 0
        }
    ],
    "fields": [
        {
        "keyword": "_test_field_value_",
        "value": "_test_field_",
        "displayOn": "approved"
        }
    ],
    "recurring": {
        "periodicity": "D",
        "interval": "1",
        "nextPayment": "2019-08-24",
        "maxPeriods": 1,
        "dueDate ": "2019-09-24",
        "notificationUrl ": "https://checkout.placetopay.com"
    },
    "subscribe": false,
    "dispersion": [
        {
        "agreement": "1299",
        "agreementType": "MERCHANT",
        "amount": {
            "currency": "USD",
            "total": 200
        }
        }
    ],
    "modifiers": [
        {
        "type": "FEDERAL_GOVERNMENT",
        "code": 17934,
        "additional": {
            "invoice": "123345"
        }
        }
    ]
}

Payment

Refund

Refund payment

Request

Request

Response

Response

Transaction actions

Request

Request

Response

Response