Desarrolladores
Soporte a desarrolladores

Autorizaci贸n y Captura

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:

  1. 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".
  2. 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": "[email protected]",
        "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": "[email protected]",
        "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": "[email protected]",
        "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": "[email protected]",
        "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
}