# Checkout API

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.

{% hint style="info" %}
Es recomendable que la integración se realice creando una cuenta en nuestro ambiente de pruebas, más información [aquí](/integraciones/checkout-api/ambiente-de-pruebas.md).
{% endhint %}

## Servicios

## Checkout Creation

<mark style="color:green;">`POST`</mark> `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                            |

{% tabs %}
{% tab title="200 Checkout created successfully" %}

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

{% endtab %}
{% endtabs %}

#### 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](/integraciones/tokenizacion.md), 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
```

{% hint style="info" %}
Puedes consultar los posibles códigos de error de este servicio [aquí](/integraciones/checkout-api/codigos-de-error.md#checkout-creation).
{% endhint %}

## 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

<mark style="color:green;">`POST`</mark> `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>        |

{% tabs %}
{% tab title="200 Checkout created sucessfully" %}

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

```

{% endtab %}
{% endtabs %}

#### 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

<mark style="color:green;">`POST`</mark> `https://www.yoursite.com/directopago/ipn`

#### Request Body

| Name      | Type   | Description              |
| --------- | ------ | ------------------------ |
| invoiceId | string | Transaction's invoice id |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

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

## Transaction status

<mark style="color:blue;">`GET`</mark> `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 |

{% tabs %}
{% tab title="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"
}
```

{% endtab %}
{% endtabs %}

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

{% hint style="info" %}
Puedes consultar los posibles códigos de error de este servicio [aquí](/integraciones/checkout-api/codigos-de-error.md#consulta-de-estado).
{% endhint %}

{% hint style="info" %}
Para ver qué moneda y tipos de documento son válidos para cada país, accede [aquí](/integraciones/checkout-api/referencia-de-paises.md).
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.directopago.com/integraciones/checkout-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.