> For the complete documentation index, see [llms.txt](https://docs.directopago.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.directopago.com/integraciones/checkout-api.md).

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