Placetopay Docs

POST/gateway/process

Procesamiento de transacción

Este servicio permite que se realice el cobro a la tarjeta del usuario, los parámetros del instrument son variables, si no se pide tipo de crédito ni otp no es necesario enviar esas variables, payer es siempre requerido, buyer es opcional pero recomendado.

Solicitud

Name
action
Type
string
is optional
Description
Este campo debe ser enviado únicamente cuando se realice un proceso de checkin, de lo contrario, no debe ser enviado en la solicitud
Valores permitidos:checkin
Name
locale
Type
string
is optional
Description
Ejemplo:es_CO
Name
auth
Type
Autenticación
is Required
REQUIRED
Description
Estructura que contiene la información de autenticación del sitio generada de acuerdo al WSSE UsernameToken Profile 1.1
Name
payer
Type
Person
is Required
REQUIRED
Description
Estructura que refleja la información de una persona involucrada en una transacción.
Name
buyer
Type
Person
is optional
Description
Estructura que refleja la información de una persona involucrada en una transacción.
Name
instrument
Type
Instrument
is Required
REQUIRED
Description
Estructura que contiene la información acerca del medio de pago a usar en una transacción, esta estructura es variable de acuerdo a la solicitud que se genere, cada servicio requiere que se usen unos u otros datos.
Name
payment
Type
Payment
is Required
REQUIRED
Description
Estructura que contiene la información acerca del pago de la transacción requerida al servicio web
Name
additional
Type
object
is optional
Description
Objeto dinámico clave valor de información que se desee guardar con la transacción. Las siguientes claves NO son permitidas: _accountNumber, userAgent, fingerprint, sourcePlatform, tokenizationID, trazabilyCode, transactionCycle, RequestId, PartnerAuthCode, onTest, threeDSEnrolled, threeDSAuthenticated. Ver más en Datos adicionales
Name
metadata
Type
object
is optional
Description
Objeto dinámico clave valor de información adicional que solicitan los servicios externos para ser ejecutados.
Name
notificationURL
Type
string
is optional
Description
URL a la que se enviará una notificación HTTP con la información de la transacción una vez que esta haya sido procesada. Ver más en Notificación
Ejemplo:https://your-site.com/your-notification-path
Name
ipAddress
Type
string
is optional
Description
Name
userAgent
Type
string
is optional
Description
Ejemplo: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

Solicitud

POST

/gateway/process

curl -X "POST" https://api-co-dev.placetopay.ws/gateway/process \
-H "Content-Type: application/json" \
-d '{
    "auth": {
        "login": "aabbccdd1234567890aabbccdd123456",
        "tranKey": "cgqVhiaKSUSJmYQsXMsBqpfjz155nyKk54I66xyfuDI=",
        "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": "3006108300"
    },
    "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"
}'

Respuesta

Name
status
Type
Status
is optional
Description
Estructura que contiene la información sobre una solicitud o pago, informa al estado actual de la misma.
Name
date
Type
string
is optional
Description
Ejemplo:2021-09-20T21:51:59-05:00
Name
transactionDate
Type
string
is optional
Description
Ejemplo:2021-09-20T21:51:59-05:00
Name
internalReference
Type
number
is optional
Description
Name
reference
Type
string
is optional
Description
Longitud mínima:1
Name
paymentMethod
Type
string
is optional
Description
Longitud mínima:1
Name
franchise
Type
string
is optional
Description
Longitud mínima:1
Name
franchiseName
Type
string
is optional
Description
Ejemplo:Botón Aval
Longitud mínima:1
Name
issuerName
Type
string
is optional
Description
Nombre del banco procesador
Ejemplo:Banco Bogotá
Longitud mínima:1
Nullable:Sí
Name
amount
Type
Amount
is optional
Description
Estructura que contiene la información acerca del pago de la transacción requerida al servicio web
Name
conversion
Type
AmountConversion
is optional
Description
Estructura para definir el factor de conversión y los valores.
Name
authorization
Type
string
is optional
Description
Longitud mínima:1
Nullable:Sí
Name
receipt
Type
string
is optional
Description
Longitud máxima:16
Nullable:Sí
Name
type
Type
string
is optional
Description
Valores permitidos:AUTH_ONLY
Longitud mínima:1
Name
refunded
Type
boolean
is optional
Description
Name
lastDigits
Type
string
is optional
Description
Longitud mínima:1
Nullable:Sí
Name
provider
Type
string
is optional
Description
Valores permitidos:ACHATH-AVALNETATH-MOVILAUSTROAVALBANCOLOMBIABRASPAGCOMFANDICREDIBANCODATAFASTEBUSEVERTECFLAMINGOINTERDINMEDIANETPAYSTUDIOREDEBANSABRESUPERGIROSTECNICARDTRANSERVERTUYA-DIRECT
Name
discount
Type
object
is optional
Description
Nullable:Sí
Name
processorFields
Type
object
is optional
Description
Name
additional
Type
object
is optional
Description
Ver más en Datos adicionales
Name
preAuthorization
Type
object
is optional
Description
Name
dispersion
Type
array
is optional
Description
Name
redirection
Type
Redirection
is optional
Description
Representa un medio de pago de redirección, es decir que requiere que se envíe el usuario a otra URL para completar el proceso
Name
notificationURL
Type
string
is optional
Description
URL a la que se enviará una notificación HTTP con la información de la transacción una vez que esta haya sido procesada. Ver más en Notificación
Ejemplo:https://your-site.com/your-notification-path

Respuesta

    {
        "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

Consulta de transacción por referencia interna

Permite consultar una transacción en particular usando su referencia interna.

Solicitud

Name
locale
Type
string
is optional
Description
Name
auth
Type
Autenticación
is Required
REQUIRED
Description
Estructura que contiene la información de autenticación del sitio generada de acuerdo al WSSE UsernameToken Profile 1.1
Name
internalReference
Type
number
is Required
REQUIRED
Description

Solicitud

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"
}'

Respuesta

Name
status
Type
Status
is Required
REQUIRED
Description
Estructura que contiene la información sobre una solicitud o pago, informa al estado actual de la misma.
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
Longitud mínima:1
Name
paymentMethod
Type
string
is Required
REQUIRED
Description
Longitud mínima:1
Name
franchise
Type
string
is Required
REQUIRED
Description
Longitud mínima:1
Name
franchiseName
Type
string
is Required
REQUIRED
Description
Longitud mínima:1
Name
issuerName
Type
string
is Required
REQUIRED
Description
Longitud mínima:1
Nullable:Sí
Name
amount
Type
Amount
is Required
REQUIRED
Description
Estructura que contiene la información acerca del pago de la transacción requerida al servicio web
Name
conversion
Type
AmountConversion
is Required
REQUIRED
Description
Estructura para definir el factor de conversión y los valores.
Name
authorization
Type
string
is Required
REQUIRED
Description
Longitud mínima:1
Nullable:Sí
Name
receipt
Type
string
is Required
REQUIRED
Description
Longitud máxima:16
Nullable:Sí
Name
type
Type
string
is Required
REQUIRED
Description
Longitud mínima:1
Name
refunded
Type
boolean
is Required
REQUIRED
Description
Name
lastDigits
Type
string
is Required
REQUIRED
Description
Longitud mínima:1
Nullable:Sí
Name
provider
Type
string
is Required
REQUIRED
Description
Valores permitidos:CREDIBANCOREDEBANINTERDINDATAFASTTUYA-DIRECTBRASPAGTRANSERVERSABREEVERTECACHATH-AVALNETSUPERGIROSTECNICARDMEDIANETAUSTROCOMFANDIPAYSTUDIOFLAMINGOATH-MOVILEBUSBANCOLOMBIA
Name
discount
Type
object
is Required
REQUIRED
Description
Nullable:Sí
Name
processorFields
Type
object
is Required
REQUIRED
Description
Name
additional
Type
object
is Required
REQUIRED
Description
Ver más en Datos adicionales
Name
preAuthorization
Type
object
is optional
Description
Name
dispersion
Type
array
is optional
Description

Respuesta

{
    "status": {
        "status": "APPROVED",
        "reason": "00",
        "message": "Aprobada",
        "date": "2024-12-04T00:09:40-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

Búsqueda de transacciones

Este servicio permite la búsqueda de transacciones por referencia y monto, suele utilizarse en caso de pérdida de comunicación al crear una transacción para obtener la referencia interna nuevamente.

Solicitud

Name
auth
Type
Autenticación
is Required
REQUIRED
Description
Estructura que contiene la información de autenticación del sitio generada de acuerdo al WSSE UsernameToken Profile 1.1
Name
reference
Type
string
is Required
REQUIRED
Description
Longitud mínima:1
Name
amount
Type
Amount
is Required
REQUIRED
Description
Estructura que contiene la información acerca del pago de la transacción requerida al servicio web

Solicitud

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
    }
}'

Respuesta

Name
status
Type
Status
is Required
REQUIRED
Description
Estructura que contiene la información sobre una solicitud o pago, informa al estado actual de la misma.
Name
transactions
Type
array
is Required
REQUIRED
Description

Respuesta

{
    "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

Operaciones sobre una transacción

Permite realizar un reembolso, re-autorización o checkout sobre una transacción existente

Solicitud

Name
locale
Type
string
is optional
Description
Ejemplo:es-CO
Name
auth
Type
Autenticación
is Required
REQUIRED
Description
Estructura que contiene la información de autenticación del sitio generada de acuerdo al WSSE UsernameToken Profile 1.1
Name
action
Type
string
is Required
REQUIRED
Description
Tipo de operación a realizar sobre la transacción

reverse para revesar una transacción. reauthorization para modificar una transacción de checkin. checkout para cerrar y cobrar una transacción de checkin. refund para rembolsar una transacción. process, para aprobar de manera manual una transacción. void para cancelar el procesamiento de una transacción pendiente de aprobación manual.
Valores permitidos:reverserefundprocessvoiddispersioncheckoutreauthorization
Ejemplo:reverse
Name
internalReference
Type
number
is Required
REQUIRED
Description
Referencia interna única de la transacción

EJ: 543423
Name
authorization
Type
string
is optional
Description
Autorización de la transacción

EJ: 9999999
Name
payment
Type
object
is optional
Description
Estructura que contiene la información acerca del pago de la transacción

Solicitud

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",
    }"

Respuesta

Name
status
Type
Status
is Required
REQUIRED
Description
Estructura que contiene la información sobre una solicitud o pago, informa al estado actual de la misma.
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
Longitud mínima:1
Name
paymentMethod
Type
string
is Required
REQUIRED
Description
Longitud mínima:1
Name
franchise
Type
string
is Required
REQUIRED
Description
Longitud mínima:1
Name
franchiseName
Type
string
is Required
REQUIRED
Description
Longitud mínima:1
Name
issuerName
Type
string
is Required
REQUIRED
Description
Longitud mínima:1
Nullable:Sí
Name
amount
Type
Amount
is Required
REQUIRED
Description
Estructura que contiene la información acerca del pago de la transacción requerida al servicio web
Name
conversion
Type
AmountConversion
is Required
REQUIRED
Description
Estructura para definir el factor de conversión y los valores.
Name
authorization
Type
string
is Required
REQUIRED
Description
Longitud mínima:1
Nullable:Sí
Name
receipt
Type
string
is Required
REQUIRED
Description
Longitud máxima:16
Nullable:Sí
Name
type
Type
string
is Required
REQUIRED
Description
Longitud mínima:1
Name
refunded
Type
boolean
is Required
REQUIRED
Description
Name
lastDigits
Type
string
is Required
REQUIRED
Description
Longitud mínima:1
Nullable:Sí
Name
provider
Type
string
is Required
REQUIRED
Description
Valores permitidos:CREDIBANCOREDEBANINTERDINDATAFASTTUYA-DIRECTBRASPAGTRANSERVERSABREEVERTECACHATH-AVALNETSUPERGIROSTECNICARDMEDIANETAUSTROCOMFANDIPAYSTUDIOFLAMINGOATH-MOVILEBUSBANCOLOMBIA
Name
discount
Type
object
is Required
REQUIRED
Description
Nullable:Sí
Name
processorFields
Type
object
is Required
REQUIRED
Description
Name
additional
Type
object
is Required
REQUIRED
Description
Ver más en Datos adicionales
Name
preAuthorization
Type
object
is optional
Description
Name
dispersion
Type
array
is optional
Description

Respuesta

    {
        "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
        }
    }