> ## Documentation Index
> Fetch the complete documentation index at: https://developer.nomba.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Recurring payments with the API

> Save a customer's card on their first payment, then charge it again whenever a payment is due.

Recurring payments let you charge a customer again without asking for their card details each time. The customer pays once with their card, which you collect on your own page and send to Nomba. Nomba saves the card and gives you a **card token** (`tokenKey`). From then on, you charge the card by sending that token.

This section uses **the API** for the first payment: you collect the customer's card details on your own page and send them to Nomba. To send the customer to the Nomba checkout page instead, see [Recurring payments with hosted checkout](/docs/products/accept-payment/recurring-payments/hosted-checkout/overview).

Use recurring payments for:

* Subscriptions and memberships
* Instalment plans
* Automatic top-ups, such as wallet or airtime reloads
* One-click repeat purchases ("Pay with saved card")

## How it works

```mermaid theme={null}
sequenceDiagram
    participant C as Customer
    participant M as Your server
    participant N as Nomba
    M->>N: Create checkout order (tokenizeCard: true)
    N-->>M: orderReference
    C->>M: Enters card details on your page
    M->>N: Submit card details
    N-->>M: responseCode T0, transactionId
    C->>M: Enters OTP
    M->>N: Submit card OTP
    N-->>M: payment_success webhook with tokenKey
    M->>M: Store tokenKey with the customer
    Note over M,N: Later, when a payment is due
    M->>N: Charge saved card (tokenKey)
    alt Bank approves
        N-->>M: status: true
    else Bank asks for an OTP
        N-->>M: otpRequired: true, transactionId
        C->>M: Enters OTP
        M->>N: Submit OTP
    end
    N-->>M: payment_success webhook
    M->>N: Verify the transaction
```

<Steps>
  <Step title="Create a checkout order">
    Create the first order with `tokenizeCard: true`. [Create a checkout order →](/docs/products/accept-payment/recurring-payments/api/create-checkout-order)
  </Step>

  <Step title="Submit card details">
    Send the card details the customer entered on your page. [Submit card details →](/docs/products/accept-payment/recurring-payments/api/submit-card-details)
  </Step>

  <Step title="Submit card OTP">
    Send the OTP from the customer's bank to complete the first payment. [Submit card OTP →](/docs/products/accept-payment/recurring-payments/api/submit-card-otp)
  </Step>

  <Step title="Store the card token">
    Read the `tokenKey` from the `payment_success` webhook and save it with your customer's record. [Store the card token →](/docs/products/accept-payment/recurring-payments/api/store-the-card-token)
  </Step>

  <Step title="Charge a saved card">
    When a payment is due, send the `tokenKey` and the amount to Nomba. [Charge a saved card →](/docs/products/accept-payment/recurring-payments/api/charge-a-saved-card)
  </Step>

  <Step title="Complete an OTP challenge, if the bank asks for one">
    Some banks ask the customer to approve a charge with an OTP. Collect it and submit it. [Complete an OTP challenge →](/docs/products/accept-payment/recurring-payments/api/complete-otp)
  </Step>

  <Step title="Confirm the charge">
    Verify the final status before you give the customer value. [Confirm the charge →](/docs/products/accept-payment/recurring-payments/api/confirm-the-charge)
  </Step>
</Steps>

## What Nomba does and what you do

| Nomba | You |
| - | - |
| Keeps the card details secure and gives you a token to charge it with | Get the customer's permission to save their card and charge it later |
| Sends the charge to the customer's bank | Store each token against the right customer |
| Tells you when the bank needs an OTP | Decide **when** to charge. Nomba charges a saved card only when you call the API. |
| Sends a webhook when a charge succeeds or fails | Collect the OTP from the customer when it's needed |
| | Verify every charge before you give value, and handle failed charges |

<Note>
  If you don't want to run your own billing schedule, use a [payment link](/docs/guides/accept-payment-with-payment-links) with a recurring frequency instead. Nomba then saves the customer's card on the first payment and charges it daily, weekly, monthly or on another schedule you choose. This guide is for merchants who want to control billing from their own server through the API.
</Note>

## Before you begin

* **API keys and an access token.** See [Obtain API keys](/docs/getting-started/get-api-keys) and [Authenticate](/docs/getting-started/authentication).
* **A webhook URL.** The card token arrives in a webhook. See [Setting up webhooks](/docs/guides/setting-up-webhooks).
* **PCI DSS compliance.** You handle the customer's card details, so your systems must be PCI DSS compliant.
* **Card payments enabled on your account.** Saving a card doesn't need to be switched on separately, but every charge on a saved card is a card payment. If card payments aren't enabled for your business, the charge is rejected with "Card payment is not supported for this order". Contact Nomba support to enable them.

## Key terms

| Term | Meaning |
| - | - |
| **Saved card** | A card that Nomba has stored so you can charge it again. A customer can have more than one. |
| **Card token (`tokenKey`)** | The value you send to charge a saved card. It isn't the card number, and it only works with your API credentials and the email it was saved with. Keep it on your server and never expose it to the browser or app. |
| **OTP challenge** | A step in which the customer's bank asks them to approve a charge with a one-time password sent to their phone or email. |

<Card title="Next: Create a checkout order" icon="arrow-right" href="/docs/products/accept-payment/recurring-payments/api/create-checkout-order">
  Create the order that saves the customer's card.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.