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:

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:

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

Categories:

eCommerce API V2

Stored Payment Methods

Overview

Storing a Payment Method

Retrieving Stored Payment Methods

Updating Stored Payment Methods

Paying with a Stored Payment Method

Contact us

Thank you!