Stored Payment Methods

Descripción general

El Método de Pago Almacenado se utiliza cuando un cliente autoriza a un comerciante a almacenar las credenciales de pago para pagos futuros. Por ejemplo, un pagador puede optar por guardar su tarjeta al finalizar la compra. En este caso, el pasarela de pagos genera un token único que vincula el número de tarjeta del pagador (PAN) con su ID en el sistema de la tienda (por ejemplo, al login del pagador).

Almacenar un Método de Pago

Puede almacenar un Método de Pago durante el pago. Para este propósito, debe crear una Session (si se utiliza integración de redirección) usando el método /sessions o crear un Payment (si se utiliza integración directa) usando el método /payments (consulte la Referencia API para más detalles). En cada uno de esos métodos, debe especificar los siguientes parámetros:

• merchantCustomerId - un identificador de su cliente, todas las tarjetas del cliente se adjuntarán a este número. Para propósitos de prueba, puede usar cualquier combinación de símbolos (de 8 a 50) como merchantCustomerId. Los símbolos permitidos son dígitos, caracteres latinos, _, y -.
• setupFutureUsage - el bloque con información sobre la categoría del Método de Pago y uso futuro. Este bloque contiene los siguientes parámetros:

Example of setupFutureUsage section:

"setupFutureUsage": {
        "category": "recurrent",
        "recurringModel": {
            "recurrent": {
                "expiry": "2025-08-24",
                "frequency": 2
            }
        }
    }

After successfull payment, the Payment Method will be stored. The identifier of the created Stored Payment Method will be returned in the following webhooks:

• paymentMethod.created - in id parameter
• payment.succeeded - in storedPaymentMethod.id parameter

For details, refer to Webhooks.

You can also retrieve the identifier of the created Stored Payment Method by sending the /payments/{id} request where id is the identifier of the Payment. The identifier of the Store Payment Method will be returned in the storedPaymentMethod.id parameter of the response. For details, refer to API Reference.

Retrieving Stored Payment Methods

Para recuperar un Método de Pago particular, use la solicitud GET paymentMethods/{id}, donde id es el identificador del Método de Pago. La Pasarela de Pagos devolverá el objeto PaymentMethod con el identificador especificado. Para más detalles, consulte la Referencia API.

Ejemplo de solicitud:

curl -X GET "https://dev.bpcbt.com/api2/paymentMethods/pm_RqN18WngsfAohSze48DUcjQSYceYqW7iJSm25RHJwSkRduEkq"\
  -H "X-Api-Key: 6HUXQFbeomV1zf5i8cgm5W8KfncENVEa5uh8RngB" \
  -H "X-Version: 2023-10-31" \

Ejemplo de respuesta:

{
    "id": "pm_RqN18WngsfAohSze48DUcjQSYceYqW7iJSm25RHJwSkRduEkq",
    "active": true,
    "card": {
        "expiryMonth": 12,
        "expiryYear": 2024,
        "holderName": "TEST CARDHOLDER",
        "maskedNumber": "411111**1111"
    },
    "category": "recurrent",
    "created": "2024-05-02T05:45:21Z",
    "merchantCustomerId": "12345",
    "type": "card"
}

También puede recuperar la lista de todos los Métodos de Pago Almacenados de un cliente particular. Para este propósito use la solicitud /customers/{id}/paymentMethods donde id es un identificador del cliente. Para más detalles, consulte la Referencia API.

Ejemplo de solicitud:

curl -X GET "https://dev.bpcbt.com/api2/customers/12345/paymentMethods" \
  -H "X-Api-Key: 6HUXQFbeomV1zf5i8cgm5W8KfncENVEa5uh8RngB" \
  -H "X-Version: 2023-10-31" \

Ejemplo de respuesta:

{
    "hasMore": false,
    "list": [
        {
            "id": "pm_RkTTfDXaEx13ayyYDayK4HpJSxex6kEmBjjQfVHSxMQUvQ6rD",
            "active": true,
            "card": {
                "expiryMonth": 12,
                "expiryYear": 2024,
                "holderName": "TEST CARDHOLDER",
                "maskedNumber": "444455**3333"
            },
            "category": "unscheduled",
            "created": "2024-04-01T03:28:58Z",
            "merchantCustomerId": "12345",
            "type": "card"
        },
        {
            "id": "pm_RqN18WngsfAohSze48DUcjQSYceYqW7iJSm25RHJwSkRduEkq",
            "active": true,
            "card": {
                "expiryMonth": 12,
                "expiryYear": 2024,
                "holderName": "TEST CARDHOLDER",
                "maskedNumber": "411111**1111"
            },
            "category": "recurrent",
            "created": "2024-05-02T05:45:21Z",
            "merchantCustomerId": "12345",
            "type": "card"
        }
    ]
}

Actualizar Métodos de Pago Almacenados

Puedes activar o desactivar el Método de Pago así como cambiar su fecha de vencimiento usando la solicitud POST /paymentMethods/{id}, donde id es el identificador del Método de Pago. La solicitud debe contener los siguientes parámetros:

• active — Indica Método de Pago activo o inactivo (true o false). Los pagos no se pueden realizar con un Método de Pago inactivo.
• expiryDate — La fecha después de la cual no se permiten pagos con este Método de Pago.

Para detalles, consulta API Reference.

Ejemplo de solicitud:

curl -X POST "https://dev.bpcbt.com/api2/paymentMethods/pm_RqN18WngsfAohSze48DUcjQSYceYqW7iJSm25RHJwSkRduEkq" \
-H "X-Api-Key: 6HUXQFbeomV1zf5i8cgm5W8KfncENVEa5uh8RngB" \
-H "X-Version: 2023-10-31" \
-H "Content-Type: application/json" \
-d '{
    "active": true,
    "expiryDate": "2025-08-24"
}'

Ejemplo de respuesta:

{
    "id": "pm_RqN18WngsfAohSze48DUcjQSYceYqW7iJSm25RHJwSkRduEkq",
    "active": true,
    "card": {
        "expiryMonth": 8,
        "expiryYear": 2025,
        "holderName": "TEST CARDHOLDER",
        "maskedNumber": "411111**1111"
    },
    "category": "recurrent",
    "created": "2024-05-02T05:45:21Z",
    "merchantCustomerId": "12345",
    "type": "card"
}

Pagar con un Método de Pago Almacenado

Para pagar usando un Método de Pago Almacenado, es necesario pasar su identificador en el parámetro storedPaymentMethod.id de la solicitud de creación de Pago (/payments). Para detalles, consulta API Reference.

Ejemplo de solicitud:

curl -X POST "https://dev.bpcbt.com/api2/payments" \
-H "X-Api-Key: 6HUXQFbeomV1zf5i8cgm5W8KfncENVEa5uh8RngB" \
-H "X-Version: 2023-10-31" \
-H "Content-Type: application/json" \
-d '{
  "amount": 11000,
  "currency": "EUR",  
  "description": "Some description",
  "merchantCustomerId": "12345",
  "metadata": {},
  "storedPaymentMethod": {
      "id": "pm_RqN18WngsfAohSze48DUcjQSYceYqW7iJSm25RHJwSkRduEkq"
  },
  "returnUrl": "https://mybestmerchantreturnurl.com/"
  }
}'