Realizar un pago

Permite realizar un cargo de manera segura y rápida.

Con la API de pagos realiza cargos a tus clientes de manera segura sin salir de tu sitio web.


📘

Antes de realizar una llamada a este endpoint, asegúrate de generar un token usando el endpoint de card token si eres PCI, o por medio del método cardToken() del SDK de Checkout Transparente si no eres PCI.


Header parameters (parámetros del encabezado)

La siguiente tabla describe el esquema de los parámetros del encabezado:

Parámetro

Descripción

Tipo

Requerido / Opcional

Notas

Content-Type

Define el formato del objeto de la llamada

application/json

Requerido

Solicitud en formato JSON

Authorization

Especifica el token de acceso

String

Requerido

token de autenticación


Body parameters (parámetros del cuerpo de la solicitud)

La siguiente tabla describe el esquema de los parámetros del body de la solicitud de pago:

Parámetro

Descripción

Tipo

Ejemplo

Requerido / Opcional

Notas

capture_method

Modo de captura en el proceso de autorización y captura

String

“automatic”

Opcional

Posibles valores: automatic o manual

El default es automatic

currency

Código de moneda en formato ISO 4217 alfabético

String

“MXN”

Requerido

Únicamente puede ser MXN

amount

Monto a cobrar

Float

100.50

Requerido

Acepta 2 decimales como máximo

payment_method

Objeto con el método de pago utilizado para completar la transacción

Objeto

token

Token ID de la tarjeta

String

"9144bbf8-e4cb-4e14-8412-d2b4d867c509"

Requerido

El token que se genera por medio del endpoint de Card token

tip_amount

Propina sobre el precio del producto o servicio que se está pagando

Float

10.50

Opcional

Si no hay propina se pasa un monto “0”. Acepta 2 decimales como máximo

description

Texto describiendo el cargo

String

“Venta de item #7”

Opcional

Formato UTF-8.

Se aceptan los siguientes caracteres especiales: ~!@#$%^&*()\\=+\\\\|\\[{\\]};:'\"/?.

No se aceptan emojis.

Longitud mínima: 1

Longitud máxima: 255

external_reference

ID de referencia de la transacción para rastrear las transacciones

String

“OID123456789”

Opcional

Longitud máxima: 36 caracteres.

Caracteres especiales permitidos: Guión medio (-) y Guión bajo (_)

Se permiten acentos.

Los espacios en blanco serán removidos.

installments

Meses sin intereses

Number

3

Opcional

Los posibles valores pueden ser: 3, 6, 9, 12, 18, 24.

El valor por default es 1, lo cuál significa que el pago no será diferido a meses.

customer

Objeto con la información del cliente para el pago

Objeto

first_name

Nombre del cliente que realiza la transacción.

String

"Dong"

Opcional

last_name

Apellido del cliente que realiza la transacción.

String

"Lee"

Opcional

email

Correo electrónico del cliente que realiza la transacción.

String

"buyer

@email.com"

Requerido

phone

Número telefónico del cliente que realiza la transacción.

String

"5555555555"

Requerido

address

Objeto con la dirección de facturación.

Objeto

Opcional

postal_code

Código postal.

String

"03800"

Opcional

Para AMEX este campo es obligatorio

street

Nombre de la calle.

String

"Av Uno"

Opcional

Para AMEX este campo es obligatorio

number

Número exterior del domicilio.

String

"104"

Opcional

Para AMEX este campo es obligatorio

city

Delegación o municipio.

String

"Benito Juárez"

Opcional

country

País.

String

"México"

Opcional

state

Estado.

String

"Ciudad de México"

Opcional

description

Texto describiendo al cliente.

String

"Gerente de la fábrica de pintura"

Opcional

identification

Objeto con los datos de la identificación del cliente.

Objeto

id

Número de identificación.

String

"TE1HCSXRS01"

Opcional

Número de folio o número de id

type

Tipo de identificación.

String

"CURP"

Opcional

Tipos pueden ser: INE, pasaporte, CURP.

webhook_url

URL del endpoint que recibirá notificaciones webhook del link de pago.

String

"https://wh.co"

Opcional

Puedes consultar la estructura de la notificación webhook en el siguiente link.


Respuesta

La respuesta contiene todos los elementos enviados en el body más los campos que se muestran en la siguiente tabla:

Parámetro

Descripción

Tipo

Notas

id

Número de identificación de la transacción.

String

Formato: UUID

amount_refunded

Cantidad reembolsada.

Float

En caso de existir un reembolso asociado con esta transacción se mostraría en este campo.

installment_amount

Monto de cada mensualidad.

Float

net_amount

Monto cobrado sin incluir propina.

Float

Contiene máximo 2 decimales.

paid_amount

Monto cobrado incluyendo propinas.

Float

Contiene máximo 2 decimales.

paid_amount

Monto final transaccionado.

Float

Contiene máximo 2 decimales.

payment_method

Objeto con el método de pago utilizado para completar la transacción

Objeto

id

Número de identificación

String

token

Token ID de la tarjeta

String

El token que se genera por medio del endpoint de Card token

type

Tipo

String

card

Objeto con la información de la tarjeta

Objeto

bin

Número BIN

String

issuer

Banco emisor

String

name

Nombre en la tarjeta

String

country

País

String

last_digits

Últimos 4 dígitos del tarjeta

String

exp_year

Año de expiración

String

exp_month

Mes de expiración

String

receipt_no

Número de recibo.

String

refunds

Array con los reembolsos asociados a este pago

Array

status

Estado del pago

String

status_detail

Detalle del estado del pago

Objeto

code

Código de estado

String

message

Descripción del estado

String

pending_action

Objeto de validación 3DS

Objeto

type

Tipo de acción pendiente para validar

String

Único posible valor es “open_modal”

url

URL para realizar la validación 3DS

String

Contiene la URL a la cuál debes redirigir al cliente para hacer la validación 3DS.

created_at

Fecha de creación.

String

Formato ISO 8601 ( YYYY-MM-DDTHH-MM-SSZ).

approved_at

Fecha de aprobación del pago.

String

Formato ISO 8601 ( YYYY-MM-DDTHH-MM-SSZ).


Código de ejemplo

Ejemplo de una llamada.

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

curl --location 'https://api.payclip.com/payments' \
--header 'Authorization: Basic MTBkMTA2Y2QtMTI4Ny00MjI1LWE0ZWQtNzY3MWRkM2Y5ZDEzOjExNWYwMjE0LWJkZDgtNGY1ZS04ODRmLWVhMTM0YjVhNTUyNA==' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": 0.01,
    "currency": "MXN",
    "description": "Test Transparent Checkout API",
    "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": 0.01,
    "tip_amount": 0,
    "amount_refunded": 0,
    "installment_amount": 0.01,
    "installments": 1,
    "capture_method": "automatic",
    "net_amount": 0.01,
    "paid_amount": 0.01,
    "captured_amount": 0.01,
    "binary_mode": false,
    "approved_at": "2024-02-27T04:14:50.868762942Z",
    "country": "MX",
    "currency": "MXN",
    "description": "Test Transparent Checkout API",
    "external_reference": "",
    "customer": {
        "address": {
            "city": "Benito Juárez",
            "country": "México",
            "colony": "San Pedro de los pinos",
            "number": "118",
            "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
}

STATUS Y STATUS_DETAIL

Al realizar un pago a través del endpoint de POST/payments reibirás los siguientes parámetros:

"status": "approved",
    "status_detail": {
        "code": "AP-PAI01",
        "message": "paid"
    }

En el parámetro “status” encontrarás el estado del pago. Los posibles valores son los siguientes:

  • Approved: El pago fue aprobado.
  • Refunded: El pago fue reembolsado.
  • Cancelled: El pago no prospero desde un estado pendiente o autorizado.
  • Rejected: El pago fue rechazado.
  • Authorized: El pago fue autorizado pero no se ha hecho el cargo.
  • Pending: El pago quedó pendiente de una acción a realizar para que prospere. Ej. Falta la autenticación 3DS.

Dentro del objeto “status_detail” podrás encontrar un código y un mensaje proporcionando más detalles acerca del status del pago.

A continuación se muestra una tabla con todos los posibles códigos y mensajes posibles:

Status

Code

Message

approved

AP-PAI01

Paid

approved

AP-REF01

Partially refunded

refunded

RE-REF01

Refunded

authorized

AU-CAP01

Pending capture

cancelled

CA-AUT01

Cancelled

cancelled

CA-MAN01

Cancelled

cancelled

CA-MER01

Cancelled

rejected

RE-BIN01

Rejected

rejected

RE-ERI03

Rejected

rejected

RE-3DS01

Fail 3DS authentication

rejected

RE-CHI01

Rejected

rejected

RE-ISS01

Not sufficient funds

rejected

RE-ISS02

Do not honour

rejected

RE-ISS03

Restricted card

rejected

RE-ISS04

Reserved for private use

rejected

RE-ISS05

Transaction not permitted to cardholder

rejected

RE-ISS06

Pick-up card

rejected

RE-ISS07

Expired card

rejected

RE-ISS08

Exceeds withdrawal amount limit

rejected

RE-ISS09

Invaliad pin (one time)

rejected

RE-ISS10

Allowable number of pin tries exceeded

rejected

RE-ISS11

Refer to card issuer

rejected

RE-ISS12

Invalid amount

rejected

RE-ISS13

Destination not available (Issuer offline)

rejected

RE-ISS14

Issuer or switch is inoperative

rejected

RE-ISS15

Visa/mc fallback

rejected

RE-ISS16

Invalid card number (no such number)

rejected

RE-ISS17

Invalid merchant

rejected

RE-ISS18

Invalid transaction

rejected

RE-ISS19

Rejected

rejected

RE-ISS20

Rejected

rejected

RE-ISS99

Generic error

pending

PE-EMV01

Waiting emv

pending

PE-SIG01

Waiting signature

pending

PE-3DS01

Waiting 3DS

pending

PE-TIC01

Waiting payment



Autenticación 3DS

Cuando un cargo requiere la autenticación 3DS, el parámetro de respuesta "pending_action" tendrá una URL; esta URL te servirá para redirigir a tus clientes para realizar la autenticación.

"pending_action": {
        "type": "open_modal",
        "url": "https://3ds.payclip.com?transaction=a679"
    }

Se debe tomar el parámetro {pending_action.url} y abrirlo dentro de un iFrame:

<iframe
      className={styles.iframe}
      title="cybersource3Ds"
      src={pending_action.url}
      data-testid="cybersource3Ds-iframe"
 />

Añadir el postMessage listener para conocer la respuesta de la autenticación:

window.addEventListener(
      `message`,
  async (event) => {
        if (event.origin === process.env.NEXT_PUBLIC_CYBERSOURCE_DOMAIN) {
          const paymentId = event.data?.paymentId;
          if (paymentId) {
            executePolling(paymentId);
          } else {
            notifyPaymentIdNotProvided();
          }
        }
      },
      false,
    );

📘

Siempre se debe evaluar: If event.origin = CYBERSOURCE_DOMAIN (https://3ds.payclip.com)

Para mayor información, consultar esta documentación mencionada en “Step 4: Step-Up IFrame” (Pág. 38).


Códigos de respuesta

La siguiente tabla contiene una lista de los códigos de respuesta y su asociación con algunos de los estados HTTP:

Estado HTTP

Error code

Mensaje

400

CL1307

card token not found

400

CL1310

installment not found or invalid

400

CL1600

Corrupted data: invalid emv amout, QPS international, invalid terminal country

400

CL1607

card token expired

400

CL2200

Input validation

400

CL2221

Invalid card holder verification method

400

CL1125

Valera not allowed for this merchant

401

CL1501

Unauthorized

500

AI1899

Internal error.


Este es un ejemplo del objeto de error en formato JSON:

{
"error_code": "CL1310",
"message": "Bad Request",
"detail": [
  "installment not found or invalid"
  ]
}

Prevención de fraudes

Recomendaciones en la prevención de fraudes

Para contar con una mejor tasa de aprobación y una clasificación adecuada del riesgo de fraude de la transacción, se recomiendan las siguientes 2 consideraciones:

  • Parámetro customer_information: Enviar información relacionado al cliente quien realiza el pago.
  • Script Clip: Incluir un Script Javascript en la pasarela de pagos.

Parámetro customer

Se recomienda enviar la información del customer para un mejor análisis de riesgo:

"customer": {
        "first_name": "Dong",
        "last_name": "Lee",
        "email": "[email protected]",
        "phone": "55555555"
        ,"address": {
            "postal_code": "1234567",
            "street": "AnyStreet",
            "number": "12456",
            "city": "Benito Juárez",
            "colony": "Ejidos de Cambray",
            "country": "México",
            "state": "Ciudad de México"
        },
        "description": "product manager",
        "identification": {
            "id": "TE02CSXRS01",
            "type": "CURP"
        }
    }

Script Clip

Clip requiere información adicional para identificar al comprador. El siguiente Script nos permite identificarlo:

<script id="cybersource" src="https://h.online-metrix.net/fp/tags.js?org_id=1snn5n9w&session_id=clip_mx${uuid}">
</script>

Donde ${uuid} (Por sus siglas “Universal Unique Identifier”), es un valor de 128 bits utilizado para identificar de forma única un objeto o entidad en Internet.

Ejemplo:

${uuid}: 7376d6ec-e9f6-48d5-a1ce-26241bd7e5d7
<script id="cybersource" src="https://h.online-metrix.net/fp/tags.js?org_id=1snn5n9w&session_id=clip_mx7376d6ec-e9f6-48d5-a1ce-26241bd7e5d7"></script>

📘

El uuid es generado por sesión y se puede tomar como ejemplo la siguiente URL: https://www.uuidgenerator.net


Notificaciones Webhook

Si se deseas recibir notificaciones webhook en tiempo real, es necesario tomar en cuenta las siguientes consideraciones:

  • Contar con un servicio para escuchar Webhook notification del comercio
  • Realizae una llamada a el endpoint GET /payments/{payment_id} de Clip

Para recibir las webhook notifications, es necesario compartir la Webhook URL cuando se consume el servicio POST /payments bajo el siguiente parámetro:

{
"webhook_url": "https://us1.make.com/64555/hooks/129782/queue/a1cb5be30d510dee6111e2386ceab85f"
}

Al consumir el servicio POST /payments, el mensaje dentro de la notificación webhook que recibirás se verá de la siguiente manera:

{
  "id": "cfd8760c-9eae-47dc-8a83-ec643bb39034"
}

Donde el parámetro “id” corresponde a ID del pago o Payment_id. Dicho valor de ID de pago debe ser consultado con la API de GET /Payments/{payment_id}.

Estarás recibiendo notificaciones webhook cuando se intente un pago, sin importar si es declinado, rechazado, pagado u otro estatus de pago.


Llamada de prueba

Puedes realizar una llamada de prueba llenando los campos necesarios en el formulario que se muestra a continuación.


Asegúrate de poner tu token de autenticación en el campo "Header: Autorization" del widget localizado a tu derecha:






Por último dale click en el botón "Try It!":




Realiza una llamada de prueba:

Language
Authorization
Header
Click Try It! to start a request and see the response here!