Stored credentials for recurring payments

Overview

When using stored credentials, your bank securely stores a customer's card details on behalf of the merchant for future use. Instead of merchants storing sensitive card information, your bank provides a stored credential reference that can be used in subsequent transactions.

Card issuers treat recurring transactions with stored credentials differently than standard transactions. For example, issuers may bypass certain validations such as card expiry checks for established recurring payment relationships.

Reuse tokens store card details for the merchant, while stored credential references enable proper recurring transactions with enhanced approval rates and additional benefits.

For example, when a merchant collects card details through a 3D Secure SIGNUP transaction, each subsequent CHARGE transaction is linked to the original sign-up. This linkage ensures that the security validations from the initial sign-up transaction carry through to all future charges.

Using stored credentials for recurring payments can lead to higher approval rates, reduced fraud risk, and improved customer experience. Therefore, we recommend implementing stored credentials for all recurring payment scenarios.

Sign-up transactions

Sign-up transactions can be a sale, account verification, pre-authorisation, or final authorisation that acts as an initial transaction where the request to store the credentials for future use is made to us. These are usually Customer-Initiated Transactions (CIT) where the cardholder provides their card details and consents to store them for future payments.

Sign-up transactions can also be Merchant-Initiated Transactions (MIT) when made through the OnlinePay API, where the merchant collects the card details and consents on behalf of the cardholder.

Charge transactions

Charge transactions use the stored credentials from a previous sign-up transaction. The processing model of the sign-up determines what type of charge transactions can follow. Recurring sign-ups can only be used for recurring charges, while non-recurring sign-ups can be used for credit on file (CIT) or unscheduled credit on file (MIT) charges.

Charge Transaction Processing Models

Sign up for recurring payments with stored credentials

To initiate a stored credential relationship for recurring payments, the merchant must first perform a SIGNUP transaction. This transaction securely captures and stores the customer's card details with your bank and returns a stored credential reference for future use.

Stored credential sign-up uses the eCommerce API endpoint as other transactions, PUT /transactions/card, and includes the stored_credential object in the request body, as well as the token_scope to define the token's usage context.

For more information about token scopes, see Tokenisation

Customer initiated (CIT) recurring SIGNUP transaction via API

The following example paylod demonstrates a customer-initiated sign-up transaction for recurring payments of $10.00 AUD, sent to the PUT /transactions/card endpoint.

{
    "payment_provider_contract": "{{paymentContract}}",
    "amount": 1000,
    "currency_code": "{{currency}}",
    "encrypted_card": "{{encryptedCard}}",
    "public_key_alias": "{{publicKeyAlias}}",
    "stored_credential": {
        "stored_credential_type": "SIGNUP",
        "processing_model_details": {
            "processing_model": "RECURRING"
        }
    },
    "token_preference": {
        "token_scope": "REUSE"
    }
}

The response includes the stored_credential object with a unique reference ID that represents the stored credential for future transactions, for example:

...
    "stored_credential": {
        "reference": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
        "processing_model": "RECURRING",
        "stored_credential_type": "SIGNUP"
    },
    "details": {
        "auto_capture": true
    },
...

Merchant initiated (MIT) recurring SIGNUP transaction via API

When the merchant initiates a recurring sign-up transaction via the API, they are responsible for obtaining and recording the cardholder's consent to store their card details for future payments. MIT sign-ups are typically used in scenarios where the merchant collects card details directly from the customer over the phone or via mail order.

The following example payload demonstrates a merchant-initiated sign-up transaction for recurring payments sent to the PUT /transactions/card endpoint.

{
    "payment_provider_contract": "{{paymentContract}}",
    "amount": 0,
    "currency_code": "{{currency}}",
    "encrypted_card": "{{encryptedCard}}",
    "public_key_alias": "{{publicKeyAlias}}",
    "auth_type": "PRE_AUTH",
    "capture_now": false,
    "stored_credential": {
        "stored_credential_type": "SIGNUP",
        "processing_model_details": {
            "processing_model": "RECURRING"
        }
    },
    "token_preference": {
        "token_scope": "REUSE"
    }
}

The key differences between CIT and MIT sign-up transactions are the inclusion of auth_type and capture_now fields. MIT sign-ups typically use pre-authorisation to verify the card details without capturing funds immediately. The amount can be set to zero for verification purposes and to establish the stored credential relationship without actually charging the card.

Merchant initiated recurring Charge transactions

Once a stored credential relationship is established through a sign-up transaction, merchants can perform charge transactions using the stored credential reference. These charge transactions can be initiated by the merchant on behalf of the customer for recurring payments.

The charge transaction uses the CHARGE type in the stored_credential object, along with the processing_model set to RECURRING. The reference field must include the stored credential reference obtained from the initial sign-up transaction. This ensures that the charge is linked to the original stored credential and improves PCI compliance and transaction approval rates.

The reference value in the example below should be replaced with the actual stored credential reference ID obtained from the SIGNUP request response.

{
    "payment_provider_contract": "{{paymentContract}}",
    "amount": 1000,
    "merchant_reference": "test123",
    "currency_code": "{{currency}}",
    "stored_credential": {
        "stored_credential_type": "CHARGE",
        "processing_model_details": {
            "processing_model": "RECURRING"
        },
        "reference": "1a2b3c-4d5e-6f7g-8h9i0j1k2l3m"
    }
}