Skip to main content

Save payment method

To save a payment method for the future use you need to generate paymentToken when you create or confirm the payment and then save it on your server. This process is often called .

Tokenization protects sensitive data through a process of replacing the data with a non-sensitive equivalent, known as a token. The token has no external significance or value. It’s a reference — or identifier — that through a tokenization system, maps back to the sensitive data. This process securely collects sensitive card information and prevents data theft.

1. Generate payment token​

When you create a payment Server-side​

POST https://api.monei.com/v1/payments
curl --request POST 'https://api.monei.com/v1/payments' \
--header 'Authorization: pk_test_3c140607778e1217f56ccb8b50540e00' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": 110,
    "currency": "EUR",
    "orderId": "14379133960355",
    "generatePaymentToken": true,
    "callbackUrl": "https://example.com/checkout/callback",
    "completeUrl": "https://example.com/checkout/complete"
}'

Check all available request parameters.

note

To retrieve the payment token for future use without charging your customer, create a payment with the following parameters:

{
  "amount": 0,
  "currency": "EUR",
  "orderId": "14379133960355",
  "transactionType": "VERIF",
  "generatePaymentToken": true,
  "callbackUrl": "https://example.com/checkout/callback",
  "completeUrl": "https://example.com/checkout/complete"
}

When you confirm a payment Server-side​

POST https://api.monei.com/v1/payments/:id/confirm
curl --request POST 'https://api.monei.com/v1/payments/26d1f09c42bb59a29b06e280f9553cd5/confirm' \
--header 'Authorization: pk_test_3c140607778e1217f56ccb8b50540e00' \
--header 'Content-Type: application/json' \
--data-raw '{
    "paymentToken": "7cc38b08ff471ccd313ad62b23b9f362b107560b",
    "generatePaymentToken": true
}'

Check all available request parameters.

When you submit a payment form Client-side​

You can pass generatePaymentToken: true when you submit a payment form. This is useful for allowing your customers to select if they want to save payment method for future use.

checkout.html
<form
  action="https://secure.monei.com/payments/{{payment_id}}/confirm"
  method="post"
  id="payment-form"
>
  <div class="card-field">
    <div id="card-input">
      <!-- A MONEI Card Input Component will be inserted here. -->
    </div>
    <!-- Used to display card errors. -->
    <div id="card-error"></div>
  </div>
  <label>
    <!-- A checkbox to save payment method -->
    <input type="checkbox" name="generatePaymentToken" value="true" />
    save payment method
  </label>
  <button type="submit" id="payment-button">Submit payment</button>
</form>

Check card payment method integration for more details.

2. Obtain and store payment token​

After the payment is completed the customer is redirected to the completeUrl with payment_id query parameter, you can obtain permanent paymentToken by calling get payment endpoint.

Store this paymentToken in your database along with customer information. Next time the customer does a purchase, create a payment with this token to skip payment form. Keep in mind that the customer will still need to complete 3d secure verification.

note

MONEI will not return paymentToken in the HTTP POST request to the callbackUrl for security reasons. You have to call get payment endpoint to retrieve the token. Generated paymentToken does not expire and should only be used server-side.

3. Charge a saved payment method​

How you charge a stored paymentToken depends on whether the customer is present:

  • (one-click) — the customer is on your site and chooses their saved card. Create a payment with the paymentToken to skip the form. The customer may still need to complete .
  • Merchant-initiated / off-session — you charge the customer when they are not present (for example, installments or your own recurring billing). Mark the first payment of the series with the sequence parameter, then charge later payments with the paymentToken and the sequenceId of that first payment. Merchant-initiated payments don't ask the customer to complete 3D Secure each time. See the create payment reference for the exact sequence fields.
tip

For standard recurring billing, use MONEI Subscriptions — it stores the payment method, handles the billing cycle, retries, and the merchant-initiated sequence for you, so you don't have to manage tokens manually.

4. Save payment methods under a customer​

Instead of storing tokens on your own server, you can let MONEI keep them under a customer. A customer is your record of one buyer. Create one with the create customer endpoint or the createCustomer GraphQL mutation.

  • Link payments. Send the customer's ID as customerId when you create a payment. MONEI saves the payment method under that customer. List the saved methods with the list payment methods endpoint or the customerPaymentMethods query.
  • Default payment method. The first reusable payment method a customer saves becomes the default (defaultTokenId). You can set defaultTokenId to another of the customer's reusable payment methods when you update the customer. MONEI only fills an empty default, so your value is kept.
  • Charge the default. Send customerId with useDefaultPaymentMethod: true and no paymentToken or paymentMethod. MONEI charges the customer's default payment method. The payment is rejected when the customer has no default.
POST https://api.monei.com/v1/payments
{
  "amount": 110,
  "currency": "EUR",
  "orderId": "14379133960356",
  "customerId": "a4e1d1dd-e0c2-4f7a-a2b1-2b0f1f9b6b1e",
  "useDefaultPaymentMethod": true
}

To delete a saved payment method, use the delete payment method endpoint. If it was the default, the default is cleared, and the next reusable payment method the customer saves becomes the new default. Deleting a customer also deletes all its saved payment methods, which is what a data-erasure request usually needs. Payments already made are kept.

warning

MONEI refuses both deletes with 409 while they are still in use. You cannot delete a customer while a subscription in ACTIVE, TRIALING, PAUSED or PAST_DUE status names it. You cannot delete a payment method while a live subscription charges it. Cancel or move those subscriptions first.

customerId on a payment is not related to paymentMethod.trustly.customerId, which is an identifier that Trustly returns for its own account holder.