Placetopay Docs

POST/gateway/process

Transaction processing

This service allows the payment to be made to the user's card, the parameters of the instrument are variables, if type of credit or OTP is not requested, it is not necessary to send these variables, payer is always required, buyer is optional but recommended.

Request

Name
action
Type
string
is optional
Description
This field should be sent when a check-in process is carried out, otherwise, it should not be sent in the request.
Allowed values:checkin
Name
locale
Type
string
is optional
Description
Example:es_CO
Name
auth
Type
Autenticación
is Required
REQUIRED
Description
Structure that contains the site authentication information generated according to the WSSE UsernameToken Profile 1.1
Name
payer
Type
Person
is Required
REQUIRED
Description
Structure that reflects the information of a person involved in a transaction.
Name
buyer
Type
Person
is optional
Description
Structure that reflects the information of a person involved in a transaction.
Name
instrument
Type
Instrument
is Required
REQUIRED
Description
Structure that contains information about the means of payment to be used in a transaction. This structure is variable according to the request that is generated. Each service requires that one or another data be used.
Name
payment
Type
Payment
is Required
REQUIRED
Description
Structure that contains the information about the payment of the transaction required to the web service
Name
additional
Type
object
is optional
Description
Dynamic Object Key Value of information that you want to save with the transaction. The following keys are NOT allowed: _accountNumber, userAgent, fingerprint, sourcePlatform, tokenizationID, trazabilyCode, transactionCycle, RequestId, PartnerAuthCode, onTest, threeDSEnrolled, threeDSAuthenticated. see more at Additional data
Name
metadata
Type
object
is optional
Description
Dynamic object key value of additional information that external services request to be executed.
Name
idempotenceKey
Type
string
is optional
Description
Unique key to identify the transaction. See more at Idempotency control
Example:ABCD1234
Max length:32
Name
notificationURL
Type
string
is optional
Description
URL to which an HTTP notification with transaction information will be sent once the transaction has been processed. See more at Notification
Example:https://your-site.com/your-notification-path
Name
ipAddress
Type
string
is optional
Description
Name
userAgent
Type
string
is optional
Description
Example:Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36
Name
sourcePlatform
Type
string
is optional
Description

Request

POST

/gateway/process

curl -X "POST" https://api-co-dev.placetopay.ws/gateway/process \
-H "Content-Type: application/json" \
-d '{
    "auth": {
        "login": "aabbccdd1234567890aabbccdd123456",
        "tranKey": "ABC123example456trankey+789abc012def3456ABC=",
        "nonce": "NjBhZTllMjZjYmQxYg==",
        "seed": "2021-05-26T14:14:46-05:00"
    },
    "payer": {
        "name": "Ms. Nelle Beahan DVM",
        "surname": "Spencer",
        "email": "[email protected]",
        "documentType": "CC",
        "document": "3154383838",
        "mobile": "3111111111"
    },
    "payment": {
        "reference": "TEST_20210526_141005",
        "description": "Cum vitae et consequatur quas adipisci ut rem.",
        "amount": {
            "currency": "COP",
            "total": 32030
        }
    },
    "instrument": {
        "card": {
            "number": "36545400000008",
            "expiration": "12/20",
            "cvv": "123"
        }
    },
    "ipAddress": "190.85.90.130",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.212 Safari/537.36"
}'

Response

Name
status
Type
Status
is optional
Description
Structure that contains information about a request or payment, informing its current status.
Name
date
Type
string
is optional
Description
Example:2021-09-20T21:51:59-05:00
Name
transactionDate
Type
string
is optional
Description
Example:2021-09-20T21:51:59-05:00
Name
internalReference
Type
integer
is optional
Description
Nullable:Yes
Name
reference
Type
string
is optional
Description
Min length:1
Name
paymentMethod
Type
string
is optional
Description
Min length:1
Nullable:Yes
Name
franchise
Type
string
is optional
Description
Min length:1
Nullable:Yes
Name
franchiseName
Type
string
is optional
Description
Example:Botón Aval
Min length:1
Nullable:Yes
Name
issuerName
Type
string
is optional
Description
Name of the processing bank
Example:Banco Bogotá
Min length:1
Nullable:Yes
Name
amount
Type
Amount
is optional
Description
Structure that contains the information about the payment of the transaction required to the web service
Name
conversion
Type
AmountConversion
is optional
Description
Structure to define the conversion factor and values.
Name
authorization
Type
string
is optional
Description
Min length:1
Nullable:Yes
Name
receipt
Type
string
is optional
Description
Max length:16
Nullable:Yes
Name
type
Type
string
is optional
Description
Allowed values:AUTH_ONLYCHECKIN
Min length:1
Name
refunded
Type
boolean
is optional
Description
Nullable:Yes
Name
lastDigits
Type
string
is optional
Description
Min length:1
Nullable:Yes
Name
provider
Type
string
is optional
Description
Allowed values:ACHATH-AVALNETATH-MOVILAUSTROAVALBANCOLOMBIABRASPAGCOMFANDICREDIBANCODATAFASTEBUSEVERTECFLAMINGOINTERDINMEDIANETPAYSTUDIOREDEBANSABRESUPERGIROSTECNICARDTRANSERVERTUYA-DIRECT
Nullable:Yes
Name
discount
Type
object
is optional
Description
Nullable:Yes
Name
processorFields
Type
object
is optional
Description
Name
additional
Type
object
is optional
Description
See more at Additional data
Name
preAuthorization
Type
object
is optional
Description
Name
dispersion
Type
array
is optional
Description
Name
redirection
Type
Redirection
is optional
Description
It represents a redirect payment method, meaning that it requires the user to be sent to another URL to complete the process.
Name
notificationURL
Type
string
is optional
Description
URL to which an HTTP notification with transaction information will be sent once the transaction has been processed. See more at Notification
Example:https://your-site.com/your-notification-path

Response

    {
        "status": {
            "status": "APPROVED",
            "reason": "00",
            "message": "Aprobada",
            "date": "2021-09-24T11:51:31-05:00"
        },
        "date": "2021-09-24T11:51:31-05:00",
        "transactionDate": "2021-09-24T11:51:31-05:00",
        "internalReference": 41,
        "reference": "ON1434012-PN1433129",
        "paymentMethod": "CR_VS",
        "franchise": "visa",
        "franchiseName": "Visa",
        "issuerName": "BANCO DE GUAYAQUIL, S.A.",
        "amount": {
            "taxes": [
            {
                "kind": "airportTax",
                "amount": 63,
                "base": 0
            },
            {
                "kind": "valueAddedTax",
                "amount": 158.47,
                "base": 0
            }
            ],
            "currency": "USD",
            "total": 1161.12
        },
        "conversion": {
            "from": {
            "currency": "USD",
            "total": 1161.12
            },
            "to": {
            "currency": "USD",
            "total": 1161
            },
            "factor": 1
        },
        "authorization": "739877",
        "receipt": "713329175945",
        "type": "DISPERSION",
        "refunded": false,
        "lastDigits": "0032",
        "provider": "CREDIBANCO",
        "discount": null,
        "processorFields": {
            "id": "08c0284b20510c8db8dcb29137374718",
            "b24": "XX"
        },
        "additional": {
            "merchantCode": "123456",
            "terminalNumber": "12345678",
            "bin": "411076",
            "expiration": "1220"
        },
        "dispersion": [
            {
            "status": {
                "status": "APPROVED",
                "reason": "00",
                "message": "Transacción aprobada",
                "date": "2021-09-24T11:51:31-05:00"
            },
            "agreement": 1,
            "type": "AIRLINE",
            "authorization": "739877",
            "receipt": "713329175945",
            "amount": {
                "currency": "CLP",
                "total": 638155.3
            },
            "refunded": false,
            "paymentMethod": "PS_VS"
            },
            {
            "status": {
                "status": "APPROVED",
                "reason": "00",
                "message": "Transacción aprobada",
                "date": "2021-09-24T11:51:31-05:00"
            },
            "agreement": null,
            "type": "MERCHANT",
            "authorization": "000000",
            "receipt": null,
            "amount": {
                "currency": "COP",
                "total": 297580
            },
            "refunded": false,
            "paymentMethod": "CR_VS"
            }
        ]
    }

POST/gateway/query

Transaction query by internal reference

Allows you to consult a particular transaction using its internal reference.

Request

Name
locale
Type
string
is optional
Description
Name
auth
Type
Autenticación
is Required
REQUIRED
Description
Structure that contains the site authentication information generated according to the WSSE UsernameToken Profile 1.1
Name
internalReference
Type
number
is Required
REQUIRED
Description

Request

POST

/gateway/query

curl -X "POST" https://api-co-dev.placetopay.ws/gateway/query \
-H "Content-Type: application/json" \
-d '{
    "locale": "es_CO",
    "auth": {
        "login":"aabbccdd1234567890aabbccdd123456",
        "tranKey":"ABC123example456trankey+789abc012def3456ABC=",
        "nonce":"NjE0OWVkODgwYjNhNw==",
        "seed":"2021-09-21T09:34:48-05:00"
    },
    "internalReference": "230364"
}'

Response

Name
status
Type
Status
is Required
REQUIRED
Description
Structure that contains information about a request or payment, informing its current status.
Name
date
Type
string
is optional
Description
EJ: 2021-09-20T21:51:59-05:00
Name
transactionDate
Type
string
is optional
Description
EJ: 2021-09-20T21:51:59-05:00
Name
internalReference
Type
number
is Required
REQUIRED
Description
Name
reference
Type
string
is Required
REQUIRED
Description
Min length:1
Name
paymentMethod
Type
string
is Required
REQUIRED
Description
Min length:1
Name
franchise
Type
string
is Required
REQUIRED
Description
Min length:1
Name
franchiseName
Type
string
is Required
REQUIRED
Description
Min length:1
Name
issuerName
Type
string
is Required
REQUIRED
Description
Min length:1
Nullable:Yes
Name
amount
Type
Amount
is Required
REQUIRED
Description
Structure that contains the information about the payment of the transaction required to the web service
Name
conversion
Type
AmountConversion
is Required
REQUIRED
Description
Structure to define the conversion factor and values.
Name
authorization
Type
string
is Required
REQUIRED
Description
Min length:1
Nullable:Yes
Name
receipt
Type
string
is Required
REQUIRED
Description
Max length:16
Nullable:Yes
Name
type
Type
string
is Required
REQUIRED
Description
Min length:1
Name
refunded
Type
boolean
is Required
REQUIRED
Description
Name
lastDigits
Type
string
is Required
REQUIRED
Description
Min length:1
Nullable:Yes
Name
provider
Type
string
is Required
REQUIRED
Description
Allowed values:CREDIBANCOREDEBANINTERDINDATAFASTTUYA-DIRECTBRASPAGTRANSERVERSABREEVERTECACHATH-AVALNETSUPERGIROSTECNICARDMEDIANETAUSTROCOMFANDIPAYSTUDIOFLAMINGOATH-MOVILEBUSBANCOLOMBIA
Name
discount
Type
object
is Required
REQUIRED
Description
Nullable:Yes
Name
processorFields
Type
object
is Required
REQUIRED
Description
Name
additional
Type
object
is Required
REQUIRED
Description
See more in Additional data
Name
preAuthorization
Type
object
is optional
Description
Name
dispersion
Type
array
is optional
Description

Response

{
    "status": {
        "status": "APPROVED",
        "reason": "00",
        "message": "Aprobada",
        "date": "2021-09-24T14:04:23-05:00"
    },
    "date": "2021-09-24T10:02:17-05:00",
    "transactionDate": "2021-09-24T10:02:18-05:00",
    "internalReference": 230364,
    "reference": "800166551",
    "paymentMethod": "ID_DN",
    "franchise": "diners",
    "franchiseName": "Diners",
    "issuerName": "Diners",
    "amount": {
        "taxes": [
        {
            "kind": "valueAddedTax",
            "amount": 0,
            "base": 0
        }
        ],
        "currency": "USD",
        "total": 120
    },
    "conversion": {
        "from": {
        "currency": "USD",
        "total": 120
        },
        "to": {
        "currency": "USD",
        "total": 120
        },
        "factor": 1
    },
    "authorization": "999999",
    "receipt": "230364",
    "type": "AUTH_ONLY",
    "refunded": false,
    "lastDigits": "0008",
    "provider": "INTERDIN",
    "discount": null,
    "processorFields": {
        "id": "cf3e77878a07d6e3ee667c60081dc39d",
        "b24": "00"
    },
    "additional": {
        "merchantCode": "1065152",
        "terminalNumber": "00990099",
        "credit": {
        "code": 1,
        "type": "03",
        "groupCode": "X",
        "installments": 3
        },
        "totalAmount": 120,
        "interestAmount": 0,
        "installmentAmount": 40,
        "iceAmount": 0,
        "batch": null,
        "line": null,
        "bin": "365454",
        "expiration": "1122"
    },
    "notificationURL": "https://test.placetopay.ec/redirection/api/notify"
}

POST/gateway/search

Transaction search

This service allows the search for transactions by reference and amount, it is usually used in case of loss of communication when creating a transaction to obtain the internal reference again.

Request

Name
auth
Type
Autenticación
is Required
REQUIRED
Description
Structure that contains the site authentication information generated according to the WSSE UsernameToken Profile 1.1
Name
reference
Type
string
is Required
REQUIRED
Description
Min length:1
Name
amount
Type
Amount
is Required
REQUIRED
Description
Structure that contains the information about the payment of the transaction required to the web service

Request

POST

/gateway/search

curl -X "POST" https://api-co-dev.placetopay.ws/gateway/search \
-H "Content-Type: application/json" \
-d '{
    "locale": "es_CO",
    "auth": {
        "login":"aabbccdd1234567890aabbccdd123456",
        "tranKey":"ABC123example456trankey+789abc012def3456ABC=",
        "nonce":"NjE0OWVkODgwYjNhNw==",
        "seed":"2021-09-21T09:34:48-05:00"
    },
    "reference": "TEST_20171108_144400"
    "amount": {
        "currency": "COP",
        "total": 1000
    }
}'

Response

Name
status
Type
Status
is Required
REQUIRED
Description
Structure that contains information about a request or payment, informing its current status.
Name
transactions
Type
array
is Required
REQUIRED
Description

Response

{
    "status": {
        "status": "OK",
        "reason": "00",
        "message": "La petición se ha procesado correctamente",
        "date": "2021-09-20T21:51:59-05:00"
    },
    "transactions": [
        {
        "status": {
            "status": "PENDING",
            "reason": "?-",
            "message": "Transacción pendiente",
            "date": "2021-09-20T21:51:59-05:00"
        },
        "date": "2021-09-20T21:51:59-05:00",
        "transactionDate": "2021-09-20T21:51:59-05:00",
        "internalReference": 453,
        "reference": "TEST_3",
        "paymentMethod": "ID_VS",
        "franchise": "visa",
        "franchiseName": "Visa",
        "issuerName": "Testing Bank",
        "amount": {
            "taxes": [
            {
                "kind": "valueAddedTax",
                "amount": 3.27,
                "base": 0
            }
            ],
            "currency": "USD",
            "total": 17.2
        },
        "conversion": {
            "from": {
            "currency": "USD",
            "total": 17.2
            },
            "to": {
            "currency": "USD",
            "total": 17.2
            },
            "factor": 1
        },
        "authorization": null,
        "receipt": null,
        "type": "AUTH_ONLY",
        "refunded": false,
        "lastDigits": "0008",
        "provider": "INTERDIN",
        "discount": null,
        "processorFields": {
            "id": "a9cb4b7a7aa03f681a0545ba6807e1fc",
            "b24": "?-"
        },
        "additional": {
            "merchantCode": "000468232",
            "terminalNumber": "00990101",
            "credit": null,
            "totalAmount": 17.2,
            "interestAmount": 0,
            "installmentAmount": 0,
            "iceAmount": 0,
            "batch": null,
            "line": null,
            "bin": "411076",
            "expiration": "1228"
        }
        },
        {
        "status": {
            "status": "PENDING",
            "reason": "?-",
            "message": "Transacción pendiente",
            "date": "2021-09-20T21:51:59-05:00"
        },
        "date": "2021-09-20T21:51:59-05:00",
        "transactionDate": "2021-09-20T21:51:59-05:00",
        "internalReference": 452,
        "reference": "TEST_3",
        "paymentMethod": "ID_VS",
        "franchise": "visa",
        "franchiseName": "Visa",
        "issuerName": "Testing Bank",
        "amount": {
            "taxes": [
            {
                "kind": "valueAddedTax",
                "amount": 3.27,
                "base": 0
            }
            ],
            "details": [
            {
                "kind": "shipping",
                "amount": 100
            }
            ],
            "currency": "USD",
            "total": 17.2
        },
        "conversion": {
            "from": {
            "currency": "USD",
            "total": 17.2
            },
            "to": {
            "currency": "USD",
            "total": 17.2
            },
            "factor": 1
        },
        "authorization": null,
        "receipt": null,
        "type": "AUTH_ONLY",
        "refunded": false,
        "lastDigits": "0008",
        "provider": "INTERDIN",
        "discount": null,
        "processorFields": {
            "id": "cbc65da9667ca078dc774cad2fd510e4",
            "b24": "?-"
        },
        "additional": {
            "merchantCode": "000468232",
            "terminalNumber": "00990101",
            "credit": null,
            "totalAmount": 17.2,
            "interestAmount": 0,
            "installmentAmount": 0,
            "iceAmount": 0,
            "batch": null,
            "line": null,
            "bin": "411076",
            "expiration": "1228"
        }
        }
    ]
}

POST/gateway/transaction

Operations on a transaction

Allows you to perform a reversal, re-authorization, refund or checkout on an existing transaction

Request

Name
locale
Type
string
is optional
Description
Example:es-CO
Name
auth
Type
Autenticación
is Required
REQUIRED
Description
Structure that contains the site authentication information generated according to the WSSE UsernameToken Profile 1.1
Name
action
Type
string
is Required
REQUIRED
Description
Type of operation to be performed on the transaction

reverse to reverse a transaction. reauthorization to modify a checkin transaction. checkout to close and collect a checkin transaction. refund to refund a transaction. process, to manually approve a transaction. void to cancel processing of a transaction pending manual approval.
Allowed values:reverserefundprocessvoiddispersioncheckoutreauthorization
Example:reverse
Name
internalReference
Type
number
is Required
REQUIRED
Description
Unique internal transaction reference

EJ: 543423
Name
authorization
Type
string
is optional
Description
Transaction Authorization

EJ: 9999999
Name
payment
Type
object
is optional
Description
Structure that contains information about the payment of the transaction

Request

POST

/gateway/transaction

    curl -X "POST" https://api-co-dev.placetopay.ws/gateway/transaction \
        -H "Content-Type: application/json" \
        -d "{
            "auth": {
                "login": "aabbccdd1234567890aabbccdd123456",
                "tranKey": "ABC123example456trankey+789abc012def3456ABC=",
                "nonce": "NjE0OWVkODgwYjNhNw==",
                "seed": "2021-09-21T09:34:48-05:00"
            },
            "internalReference": "1505723583",
            "authorization": "999999"
            "action": "reverse",
        }"

Response

Name
status
Type
Status
is Required
REQUIRED
Description
Structure that contains information about a request or payment, informing its current status.
Name
date
Type
string
is optional
Description
Date when the transaction was created (ISO 8601, timezone offset required). Example: 2021-09-20T21:51:59-05:00.
Format:date-time
Name
transactionDate
Type
string
is optional
Description
Processing date at provider (may differ from date).
Format:date-time
Name
internalReference
Type
number
is Required
REQUIRED
Description
Platform internal reference.
Name
reference
Type
string
is Required
REQUIRED
Description
Merchant order reference.
Min length:1
Name
paymentMethod
Type
string
is Required
REQUIRED
Description
Conventional format: processor_franchise (e.g., ID_VS for Interdin Visa, DF_MS for Datafast Mastercard), exceptions may exist.
Max length:5
Min length:5
Name
franchise
Type
string
is Required
REQUIRED
Description
Franchise code.
Allowed values:visavisa_electronamexmastercodensadinersjbcdiscoverriscredencialcomfamacolsubsidiofalabellaelosomostuyaexitoalkostomaestromefiaath_cardathathmvbancolombiacooperativadebitopagoefectivocafamefectyganamasterpassppdpsesafetypaysupergirosvisa_checkoutprocesacomfandiachteleredavaldilobanco_bogotaebtalia
Name
franchiseName
Type
string
is Required
REQUIRED
Description
Franchise display name.
Min length:1
Name
issuerName
Type
string
is optional
Description
Issuing bank name.
Min length:1
Nullable:Yes
Name
amount
Type
Amount
is Required
REQUIRED
Description
Structure that contains the information about the payment of the transaction required to the web service
Name
conversion
Type
AmountConversion
is optional
Description
Structure to define the conversion factor and values.
Name
authorization
Type
string
is Required
REQUIRED
Description
Authorization code.
Max length:32
Min length:1
Nullable:Yes
Name
receipt
Type
string
is Required
REQUIRED
Description
Receipt / ticket number.
Max length:16
Min length:1
Nullable:Yes
Name
type
Type
string
is Required
REQUIRED
Description
Transaction operation type.
Allowed values:AUTH_ONLYAUTH_CAPTURECAPTURE_ONLYCREDITSETTLEVOIDCHARGEBACKDISPUTEDISPUTE_LOSSDISPUTE_WINDISPERSIONREFUNDPRE_AUTHCHECKINCHECKOUTRE_AUTHDISPERSION_CAPTUREDISPERSION_SETTLEDISPERSION_CREDIT
Min length:1
Name
refunded
Type
boolean
is Required
REQUIRED
Description
Refunded flag.
Name
lastDigits
Type
string
is optional
Description
Masked card, last digits.
Min length:2
Nullable:Yes
Name
provider
Type
string
is Required
REQUIRED
Description
Processor/provider code.
Allowed values:CREDIBANCOREDEBANINTERDINDATAFASTTUYA-DIRECTBRASPAGTRANSERVERSABREEVERTECACHATH-AVALNETSUPERGIROSTECNICARDMEDIANETAUSTROCOMFANDIPAYSTUDIOFLAMINGOATH-MOVILEBUSBANCOLOMBIA
Name
discount
Type
object
is optional
Description
Applied discount info.
Nullable:Yes
Name
processorFields
Type
object
is Required
REQUIRED
Description
Raw processor fields.
Name
additional
Type
object
is optional
Description
See more in Additional data
Name
preAuthorization
Type
object
is optional
Description
Pre-authorization segments.
Name
dispersion
Type
array
is optional
Description
Dispersion splits list.

Response

    {
        "status": {
            "status": "APPROVED",
            "reason": "00",
            "message": "Aprobada",
            "date": "2024-09-25T14:17:56-05:00"
        },
        "date": "2024-09-25T14:17:53-05:00",
        "transactionDate": "2024-09-25T14:17:56-05:00",
        "internalReference": 9,
        "reference": "331122",
        "paymentMethod": "CR_VS",
        "franchise": "visa",
        "franchiseName": "Visa",
        "issuerName": "JPMORGAN CHASE BANK, N.A.",
        "amount": {
            "taxes": [
                {
                    "kind": "valueAddedTax",
                    "amount": 0,
                    "base": 0
                }
            ],
            "currency": "COP",
            "total": 20000
        },
        "conversion": {
            "from": {
                "currency": "COP",
                "total": 20000
            },
            "to": {
                "currency": "COP",
                "total": 20000
            },
            "factor": 1
        },
        "authorization": "000000",
        "receipt": null,
        "type": "CREDIT",
        "refunded": false,
        "lastDigits": "1111",
        "provider": "CREDIBANCO",
        "discount": null,
        "processorFields": {
            "id": "0aba335e6b5a67822150e27f98949b3a",
            "b24": "000"
        },
        "additional": {
            "merchantCode": "012988341",
            "terminalNumber": "00022645",
            "bin": "411111",
            "expiration": "0525",
            "installments": 1
        }
    }