Stored Payment Methods

Overview

Stored Payment Method is used when a customer authorizes a merchant to store the payment credentials for further payments. For example, a payer may opt to save their card at checkout. In this case a unique token is generated by the Payment Gateway that links the payer's card number (PAN) to their ID in the store system (for example, to payer's login).

Storing a Payment Method

You can store a Payment Method during payment. For this purpose, you should create a Session (if redirect integration is used) using the /sessions method or create a Payment (if redirect of direct integration is used) using the /payments method (see the API Reference for details). In each of those methods, you should specify the following parameters:

• merchantCustomerId - an identifier of your customer, all the customer’s cards will be attached to this number. For test purposes, you may use any combination of symbols (from 8 to 50) as merchantCustomerId. Allowed symbols are digits, latin characters, _, and -.
• setupFutureUsage - the block with information about the Payment Method category and future usage. This block contains the following parameters:

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 storedPaymentMethodId 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 storedPaymentMethodId parameter of the response. For details, refer to API Reference.

Retrieving Stored Payment Methods

To retrieve a particular Payment Method, use paymentMethods/{id} GET request, where id is the identifier of the Payment Method. Payment Gateway will return the PaymentMethod object with the specified identifier. For details, refer to API Reference.

Request example:

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

Response example:

{
    "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"
}

You can also retrieve the list of all Stored Payment Methods of a particular customer. For this purpose use /customers/{id}/paymentMethods request where id is an identifier of the customer. For details, refer to API Reference.

Request example:

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

Response example:

{
    "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"
        }
    ]
}

Updating Stored Payment Methods

You can activate or deactivate Payment Method as well as change its expiration date using the /paymentMethods/{id} POST request, where id is the identifier of the Payment Method. The request must contain the following parameters:

• active — Indicates active or inactive Payment Method (true or false). Payments cannot be made with an inactive Payment Method.
• expiryDate — The date after which payments are not allowed with this Payment Method.

For details, refer to API Reference.

Request example:

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"
}'

Response example:

{
    "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"
}

Paying with a Stored Payment Method

To pay using a Stored Payment Method, it is necessary to pass its identifier in the storedPaymentMethodId parameter of Payment creation request (/payments). For details, refer to API Reference.

Request example:

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": {},
  "storedPaymentMethodId": "pm_RqN18WngsfAohSze48DUcjQSYceYqW7iJSm25RHJwSkRduEkq",
  "returnUrl": "https://mybestmerchantreturnurl.com/"
  }
}'