For any question, we are one click away

Contact us

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:

Mandatory Name Type Description
Mandatory category String Category of the Payment Method that will be stored for future usage. Allowed values:
  • empty — Payment Method is not stored;
  • unscheduled — for payments that are not related to any plan or schedule. For example, when a customer makes a new order and pays for it using previously saved card data.
  • recurrent — for payments that occur on a fixed schedule. For example, monthly utility bills.
  • installment — for payment by installments, when a customer pays a bill in small portions throughout a fixed period of time according to a payment plan.
Conditional recurringModel Object Additional configuration parameters for Recurrent and Installment payment method categories. Is mandatory when recurrent or incremental category is used.
Conditional recurringModel.recurrent Object Recurrent payment attributes. Is mandatory when recurrent category is used.
Mandatory recurringModel.recurrent.expiry String The date after which payments are not allowed. The format is "YYYY-MM-dd".
Mandatory recurringModel.recurrent.frequency Number Minimum number of days between payments (<=4000).
Conditional recurringModel.installment Object Recurrent payment attributes. Is mandatory when incremental category is used.
Mandatory recurringModel.installment.expiry String The date after which payments are not allowed.
Mandatory recurringModel.installment.frequency Number Minimum number of days between payments (<=4000).
Mandatory recurringModel.installment.phase Number Maximum number of allowed authorizations for installment payments. (<=1000).

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:

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:

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/"
  }
}'
Categories:
eCommerce API V2
Categories
Search results