La autorización es el proceso de verificar la disponibilidad de fondos y colocar una retención sobre ellos, y la captura confirma y procesa la transacción.

📘
Para realizar una autorización necesitas generar un Card Token ID usando el endpoint de POST/card_tokens o el SDK de checkout transparente.

Introducción

El flujo consiste en 2 etapas principales:

Autorización
a. Tokeniza la tarjeta usando el endpoint de POST /card_tokens o el SDK de checkout transparente..
b. Usar el card token ID para procesar el pago usando el endpoint de POST /payments enviando el parámetro "capture_method":"manual".
Captura
a. Aprobar la autorización con el mismo monto.
b. Cancelar la autorización (Opcional)

La autorización consiste en hacer una retención temporal del monto a cobrar con el fin de validar la disponibilidad de los fondos y retenerlos. Una vez realizada una autorización, tienes hasta 30 días naturales para hacer la captura y confirmar el cargo, de lo contrario esa autorización expira y ya no se retienen los fondos en la tarjeta. También puedes cancelar la autorización si ya no deseas realizar el cargo correspondiente.

Por último se hace la captura, la cual consiste en confirmar el cargo, y únicamente puede ser por el mismo monto de la autorización, esta detona el procesamiento de la transacción. Si necesitas cancelar una captura o cargo después de procesado, lo puedes hacer a través de nuestra API de reembolsos.

Autorización

Parámetro capture_method

El parámetro "capture_method" le indica a la API si la captura o cargo se debe realizar de forma manual o automática. Para el caso de una autorización sin captura, deberemos indicar que será una captura manual, de esta forma:

{
"capture_method": "manual"
}

Si en la respuesta nos muestra un status "authorized" con el código AU-CAP01: "Pending capture", quiere decir que la autorización fue exitosa:

 "status": "authorized",
    "status_detail": {
        "code": "AU-CAP01",
        "message": "Pending capture"
    }

La definición completa de los parámetros para realizar un pago la puedes consultar aquí.

En caso de recibir un status "pending" con un código "PE-3DS01" y un mensaje "Waiting 3DS", será necesario realizar la autenticación 3DS:

"status": "pending",
"status_detail": {
  "code": "PE-3DS01",
  "message": "Waiting 3DS"
}

Código de ejemplo

Ejemplo de una llamada.

El siguiente bloque de código muestra un ejemplo de la solicitud cURL:

curl --location --request POST 'https://api.payclip.com/payments' \
--header 'Authorization: Basic MTBkMTA2Y2QtMTOjExNWYwMjE0LWJkZDgtNGY1ZS04ODRmLWVhMTM0YjVhNTUyNA==' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": 1000,
    "currency": "MXN",
    "description": "Prueba Autorización",
    "capture_method": "manual",
    "payment_method": {
        "token": "0915e7-f6f-862-89e-0c5d71ae6"
    },
    "customer": {
        "email": "correo@ejemplo.com",
        "phone": "5555555555"
    }
}'

Ejemplo de un objeto de la respuesta.

El siguiente objeto es una respuesta de éxito con código HTTP 201 OK:

{
    "id": "3d62e0-57a8-d22-a90-d59e0d94f",
    "amount": 1000,
    "tip_amount": 0,
    "amount_refunded": 0,
    "installment_amount": 1000,
    "installments": 1,
    "capture_method": "manual",
    "net_amount": 1000,
    "paid_amount": 1000,
    "captured_amount": 1000,
    "binary_mode": false,
    "approved_at": "2024-02-27T04:14:50.868762942Z",
    "country": "MX",
    "currency": "MXN",
    "description": "Prueba Autorización",
    "external_reference": "",
    "customer": {
        "address": {
            "city": "Benito Juárez",
            "country": "México",
            "colony": "San Pedro de los pinos",
            "external_number": "118",
            "internal_number": "Depto 11",
            "postal_code": "03800",
            "state": "ciudad de México",
            "street": "Av Uno"
        },
        "description": "Descripción",
        "email": "correo@ejemplo.com",
        "first_name": "John",
        "last_name": "Doe",
        "identification": {
            "id": "INE",
            "type":"123456"
        },        
        "phone": "5555555555",
    },
    "payment_method": {
        "id": "master",
        "type": "credit_card",
        "card": {
            "bin": "555555",
            "issuer": "SANTANDER PR",
            "name": "John Doe Doe",
            "country": "MX",
            "last_digits": "2222",
            "exp_year": "99",
            "exp_month": "12"
        },
        "token": "0915e7-f6f-862-89e-0c5d71ae6"
    },
    "pending_action": {},
    "receipt_no": "SzWn",
    "refunds": [],
    "statement_descriptor": "",
    "status": "approved",
    "status_detail": {
        "code": "AU-CAP01",
        "message": "Pending capture"
    },
    "metadata": {},
    "return_url": "",
    "webhook_url": "",
    "created_at": "2024-02-27T04:14:49.687206862Z",
    "version": 0
}

Captura

Para realizar la captura deberás actualizar el status del pago realizando una solicitud al endpoint PATCH /payments/{payment_id} indicando lo siguiente:

"paid_amount": Este es el monto a cobrar, el cuál debe ser un monto igual o menor al de la autorización.
"status": Para realizar el cargo, el status debe ser "approved"

La solicitud se hace de la siguiente forma:

curl --location --request PATCH 'https://api.payclip.com/payments/3d62e0-57a8-d22-a90-d59e0d94f' \
--header 'Authorization: Basic MTBkMTA2Y2QtMTOjExNWYwMjE0LWJkZDgtNGY1ZS04ODRmLWVhMTM0YjVhNTUyNA==' \
--header 'Content-Type: application/json' \
--data-raw '{
    "paid_amount": 1000,
    "status": "approved"
}'

La respuesta será la misma que en el endpoint POST/payments con el status final del pago, ejemplo:

{
    "id": "3d62e0-57a8-d22-a90-d59e0d94f",
    "amount": 1000,
    "tip_amount": 0,
    "amount_refunded": 0,
    "installment_amount": 1000,
    "installments": 1,
    "capture_method": "manual",
    "net_amount": 1000,
    "paid_amount": 1000,
    "captured_amount": 1000,
    "binary_mode": false,
    "approved_at": "2024-02-27T04:14:50.868762942Z",
    "country": "MX",
    "currency": "MXN",
    "description": "Prueba Autorización",
    "external_reference": "",
    "customer": {
        "address": {
            "city": "Benito Juárez",
            "country": "México",
            "colony": "San Pedro de los pinos",
            "external_number": "118",
            "internal_number": "Depto 11",
            "postal_code": "03800",
            "state": "ciudad de México",
            "street": "Av Uno"
        },
        "description": "Descripción",
        "email": "correo@ejemplo.com",
        "first_name": "John",
        "last_name": "Doe",
        "identification": {
            "id": "INE",
            "type":"123456"
        },        
        "phone": "5555555555",
    },
    "payment_method": {
        "id": "master",
        "type": "credit_card",
        "card": {
            "bin": "555555",
            "issuer": "SANTANDER PR",
            "name": "John Doe Doe",
            "country": "MX",
            "last_digits": "2222",
            "exp_year": "99",
            "exp_month": "12"
        },
        "token": "0915e7-f6f-862-89e-0c5d71ae6"
    },
    "pending_action": {},
    "receipt_no": "SzWn",
    "refunds": [],
    "statement_descriptor": "",
    "status": "approved",
    "status_detail": {
        "code": "AP-PAI01",
        "message": "paid"
    },
    "metadata": {},
    "return_url": "",
    "webhook_url": "",
    "created_at": "2024-02-27T04:14:49.687206862Z",
    "version": 0
}

En caso de que quieras cancelar o reembolsar un cargo o captura, lo puedes hacer a través de nuestra API de Reembolsos.

Cancelar una autorización

Para cancelar una autorización deberás actualizar el status del pago realizando una solicitud al endpoint PATCH /payments/{payment_id} indicando lo siguiente:

"status": Para cancelar la autorización, el status debe ser "cancelled".

La solicitud se hace de la siguiente forma:

curl --location --request PATCH 'https://api.payclip.com/payments/3d62e0-57a8-d22-a90-d59e0d94f' \
--header 'Authorization: Basic MTBkMTA2Y2QtMTOjExNWYwMjE0LWJkZDgtNGY1ZS04ODRmLWVhMTM0YjVhNTUyNA==' \
--header 'Content-Type: application/json' \
--data-raw '{
    "status": "cancelled"
}'

Si en la respuesta nos muestra un status "cancelled" con el código CA-MER01: "Cancelled", quiere decir que la cancelación de la autorización fue exitosa:

"status": "cancelled",
"status_detail": {
    "code": "CA-MER01",
    "message": "Cancelled"
}

Esta cancelación significa que no se hará ningún cargo a la tarjeta.

Ejemplo de una respuesta completa con el status "cancelled":

{
    "id": "3d62e0-57a8-d22-a90-d59e0d94f",
    "amount": 1000,
    "tip_amount": 0,
    "amount_refunded": 0,
    "installment_amount": 1000,
    "installments": 1,
    "capture_method": "manual",
    "net_amount": 1000,
    "paid_amount": 1000,
    "captured_amount": 1000,
    "binary_mode": false,
    "approved_at": "2024-02-27T04:14:50.868762942Z",
    "country": "MX",
    "currency": "MXN",
    "description": "Prueba Autorización",
    "external_reference": "",
    "customer": {
        "address": {
            "city": "Benito Juárez",
            "country": "México",
            "colony": "San Pedro de los pinos",
            "external_number": "118",
            "internal_number": "Depto 11",
            "postal_code": "03800",
            "state": "ciudad de México",
            "street": "Av Uno"
        },
        "description": "Descripción",
        "email": "correo@ejemplo.com",
        "first_name": "John",
        "last_name": "Doe",
        "identification": {
            "id": "INE",
            "type":"123456"
        },        
        "phone": "5555555555",
    },
    "payment_method": {
        "id": "master",
        "type": "credit_card",
        "card": {
            "bin": "555555",
            "issuer": "SANTANDER PR",
            "name": "John Doe Doe",
            "country": "MX",
            "last_digits": "2222",
            "exp_year": "99",
            "exp_month": "12"
        },
        "token": "0915e7-f6f-862-89e-0c5d71ae6"
    },
    "pending_action": {},
    "receipt_no": "SzWn",
    "refunds": [],
    "statement_descriptor": "",
    "status": "cancelled",
    "status_detail": {
        "code": "CA-MER01",
        "message": "Cancelled"
    },
    "metadata": {},
    "return_url": "",
    "webhook_url": "",
    "created_at": "2024-02-27T04:14:49.687206862Z",
    "version": 0
}