Checkout API

Genera links de checkout para tus clientes utilizando nuestra API. Recibe notificaciones cuando cambie el estado de una transacción. Crea cobros directos a tarjetas guardadas.

Esta sección cubre los conceptos básicos de los servicios y los detalles técnicos de la API REST de Directo Pago. Contiene ejemplos funcionales de las solicitudes y observaciones importantes que deben tenerse en cuenta durante la integración.

Todas las llamadas a la API devolverán respuestas JSON, incluidos errores.

Es recomendable que la integración se realice creando una cuenta en nuestro ambiente de pruebas, más información aquí.

Servicios

Checkout Creation

POST https://checkout-api.directopago.com/v1/checkout

Headers

Name	Type	Description
Authorization	string	Bearer + Directo Pago API key

Request Body

Name	Type	Description
country	string	Checkout country (ISO code)
amount	number	Amount to be paid by the client (5 decimals max)
currency	string	Amount currency. Default value: USD
invoiceId	string	Unique invoice identifier on the merchant end. If not sent, it will be automatically generated
clientId	string	Unique client identifier on the merchant end. If not sent, it will be automatically generated
clientFirstName	string	Client's first name
clientLastName	string	Client's last name
clientDocumentType	string	Client's document type. Must be a valid document type for the specified country
clientDocument	string	Client's document number. Must be a valid document for the specified country and clientDocumentType
clientEmail	string	Client's email
clientAddress	string	Client's address
clientCity	string	Client's city
clientState	string	Client's state
clientZipCode	string	Client's zip code. Must be valid for the specified country
clientMobilePhone	string	Client's mobile phone. Must be valid for the specified country
logo	string	Merchant logo HTTPS URL to be used in checkout (overrides the logo defined in the merchant panel)
backUrl	string	Merchant website URL used to return the client to your website
successUrl	string	Merchant website URL used to redirect the client after a successful checkout

200 Checkout created successfully

{
    "url": "http://checkout.directopago.com/validate/870suVaMTT14EGHX7y61o5Lp0XLmPo6V"
}

Example request:

curl -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer PGickJNyZHrcNWZjZbewzLDtdoOrpuIM' \
    -d '{body}'
    https://checkout-api.directopago.com/v1/checkout

Simplest request Body (Creates a checkout for every supported country in USD):

{
	"amount": 10
}

Request Body for a specific country and currency:

{
	"amount": 10,
	"currency": "USD",
	"country": "MX"
}

Cobros con cardId

Para realizar un cobro con un cardId guardado previamente mediante nuestra solución de Tokenización, se debe hacer de la siguiente manera:

Request Body:

{
    "amount": "100",
    "currency": "USD",
    "cardToken": "CID-6051f971-1193-4f59-8aa3-f03bdba3adc6"
}

Response Body:

{
    "invoiceId": "126307563352994",
    "country": "MX",
    "amount": 100,
    "currency": "USD",
    "localAmount": 2000,
    "localCurrency": "MXN",
    "createdDate": "2021-07-08T17:36:44.191553",
    "status": "COMPLETED"
}

Borrar tarjeta guardada:

curl -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer PGickJNyZHrcNWZjZbewzLDtdoOrpuIM' \
    https://checkout-api.directopago.com/v1/cards/CID-6051f971-1193-4f59-8aa3-f03bdba3adc6

Puedes consultar los posibles códigos de error de este servicio aquí.

Notificaciones de cambios de estado

Al crear un checkout, se permite enviar una URL a la cual se notificarán los cambios de estado que ocurran sobre la transacción creada.

Checkout creation with notification URL

POST https://checkout-api.directopago.com/v1/checkout

Headers

Name	Type	Description
Authorization	string	Bearer + Directo Pago API key

Request Body

Name	Type	Description
country	string	Checkout country (ISO code)
amount	number	Amount to be paid by client (5 decimals max)
currency	string	Amount currency. If not specified, USD is assumed
notificationUrl	string	https://www.yoursite.com/directopago/ipn

200 Checkout created sucessfully

{
    "url": "http://checkout.directopago.com/validate/870suVaMTT14EGHX7y61o5Lp0XLmPo6V"

Example request:

curl -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer PGickJNyZHrcNWZjZbewzLDtdoOrpuIM' \
    -d '{body}'
    https://checkout-api.directopago.com/v1/checkout

Request body:

{
	"amount": 10,
	"currency": "USD",
	"country": "MX",
	"notificationUrl": "https://www.yoursite.com/directopago/ipn"
}

Ejemplo de notificación

POST https://www.yoursite.com/directopago/ipn

Request Body

Name	Type	Description
invoiceId	string	Transaction's invoice id

200

Cuando se recibe una notificación de cambio de estado, se debe consultar al siguiente servicio con su API Key correspondiente.

Transaction status

GET https://checkout-api.directopago.com/v1/transactions/{invoiceId}

Path Parameters

Name	Type	Description
invoiceId	string	Transaction's invoice id

Headers

Name	Type	Description
Authorization	string	Bearer + Directo Pago API key

200

{    
    "client_id": "1234680",    
    "transaction_id": 2,    
    "invoice_id": "12033902754885",    
    "country": "BR",    
    "currency": "BRL",    
    "usd_amount": 26.39,    
    "local_amount": 155.70,    
    "payment_method_type": "VOUCHER",    
    "status": "COMPLETED"
}

Example request:

curl -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer PGickJNyZHrcNWZjZbewzLDtdoOrpuIM' \
    https://checkout-api.directopago.com/v1/transactions/12033902754885

Estados posibles para una transacción: PENDING, COMPLETED, CANCELLED, DECLINED.

Puedes consultar los posibles códigos de error de este servicio aquí.

Para ver qué moneda y tipos de documento son válidos para cada país, accede aquí.