Developer Documents

This page provides an overview of the Stored Credentials Framework for Visa and Mastercard, explains how we’ve implemented support for it, and describes how merchants who may need to override our treatment of their transactions can do so. You should read this documentation in conjunction with any information your acquiring bank has provided you with. If you are not sure how this mandate applies to you, or how it relates to your business model, please consult your acquirer.

• Overview of Stored Credentials
• Displaying the cardholder agreement
• How Pay360 determines the default attributes of a transaction
• Overriding Stored Credential attributes of a transaction
• Response Elements

When a merchant (or their agent) processes a transaction and stores payment credentials for later use, they must:

• obtain consent from the cardholder to store their payment details, and establish a clear agreement for how and when they may be reused
• indicate (as part of the transaction authorisation) that the payment credentials are being stored for future reuse
• store the scheme reference (also known as the scheme transaction ID or [payment] network transaction ID) for this transaction

When a transaction is processed using stored payment credentials, the transaction authorisation must indicate that existing stored credentials are being reused, and provide the scheme reference corresponding to the initial transaction where those credentials were stored.

This applies both in cases where the payment credentials will be stored for reuse only by direct engagement with the cardholder (such as when a cardholder chooses to save their card in a virtual wallet, such as in our Hosted Cashier, to save re-entering those details in the future), as well as when the merchant will use the stored payment credentials to process transactions without further cardholder involvement, such as in a recurring or instalment agreement.

The implicit storage of payment credentials to facilitate refunds and other types of credit, as well as deferred payments (with delayed capture), is not considered “storage” for the purpose of this mandate; a payment credential is considered to be reused only when it is used to process a new payment transaction or account verification.

Pay360 will ensure that transactions are processed with the correct indicators; as described below, in most cases, we don’t need any additional information from merchants to determine what these will be. We will also store and re-present the scheme reference on your behalf, if we have received one.

Merchants (or their agents) are responsible for ensuring that they establish a clear agreement with their cardholders as to when their payment credentials will be stored, and how and when they may be reused. This should normally include:

• the basis on which future transactions will be processed without involving the cardholder
• the duration of any trial period, introductory offer, or promotional period
• transaction amounts and the timing of any subsequent transactions
• instructions on how to cancel the agreement and/or any subsequent transactions

Visa requires that this information is shown to cardholders on the same page that is used to collect payment details.

If you are using our Hosted payment form, then a customer notice may be used for this; its content can be varied on a per-session basis.

POST /hosted/rest/sessions/{instId}/payments
{
    "transaction": {
        "money": {
            "currency": "GBP",
            "amount": {
                "fixed": "5.99"
            }
        },
        "recurring": true
    },
    "session": {
        "returnUrl": {
            "url": "https://www.example.com"
        }
    },
    "customerNotice": {
        "content": "You agree that we may store your card details and bill them monthly for the amount shown according to our subscription agreement. You can cancel via the <em>Your Subscriptions</em> section of our web site.",
        "locator": "FORM_BOTTOM"
    }
}


HTTP/1.1 201 Created
{
    "sessionId": "SMjoRfLbhNUpIkLhrIk2zLrJr",
    "redirectUrl": "https://secure.mite.pay360.com/hosted/SMjoRfLbhNUpIkLhrIk2zLrJr/begin/SMjoRfLbhNUpIkLhrIk2zLrJr",
    "status": "SUCCESS"
}

See Customer Notice for more information, including how to change the appearance using a custom skin.

We have implemented a default classification for transactions that we believe will cater for most common use cases our merchants have.

Unless you tell us otherwise (see below), we assume that you are not storing payment credentials in your own system, and so assume that if you provide us with payment credentials, they have been sourced from the cardholder, who has initiated the transaction.

Most merchants should not need to override this default behaviour.

Customer Initiated

We assume that a transaction was customer initiated (CIT) if any of the following apply:

• a card security code (CVV2/CVC2/CID etc.) is provided
• a card number (PAN) is provided
• a CardLock token is provided
• the transaction is processed via the Hosted Cashier
• 3D Secure requested i.e.transactionOptions.do3DSecure = true

Otherwise, we assume that the transaction is merchant initiated (MIT). We always treat REPEAT requests as merchant initiated.
For merchant initiated (MIT), 3D Secure will never be performed.

Storage

We consider that a payment credential is being stored if we will be storing it on your behalf and facilitating future transactions, i.e. by:

• providing you with a merchant token to be used in future requests
• initiating a recurring or instalment transaction sequence

Conversely, if the payment credentials will not be made re-usable in the future, then we will process accordingly. This occurs when:

• you specify paymentMethod.registered = false
• for hosted sessions, you choose to allow your customers to decide whether their payment method will be stored (features.paymentMethodRegistration = optional), and a customer elects not to store it (deselects “save my card”)

We consider that a stored payment credential is being reused whenever you use one of the available mechanisms to access one, i.e.:

• using a merchant token instead of a card number
• processing a subsequent recurring or instalment transaction (via a REPEAT)

Agreement

We infer that there is a recurring agreement in place for reuse of stored payment credentials whenever the standard recurring workflow is in use, i.e.:

• when processing a payment or account verification transaction marked as initial recurring (transaction.recurring = true)
• when processing a subsequent recurring transaction (using the REPEAT operation)

Similarly, we infer that there is an instalment agreement in place whenever the standard instalment workflow in use, i.e.:

• when processing a payment or account verification transaction marked as initial instalment (transaction.instalment = true)
• when processing a subsequent instalment transaction (using the REPEAT operation)

Otherwise, we will infer that any agreement to reuse a stored payment credential is for ad-hoc/un-scheduled reuse, subject to a documented agreement with the cardholder.

Scheme Reference

We will return any scheme reference that the acquirer returns to us for a given transaction; see “Response Elements” below. When payment credentials are being stored for reuse, we will automatically store the reference on your behalf, associated with the payment credentials in use, and will use it in the future unless:

• we determine that the reference cannot be reused (based on acquirer restrictions)
• you provide us with a specific reference to be used instead (in paymentMethod.reuse.originalSchemeReference)

For existing stored payment credentials where a suitable scheme reference has not already been stored, we will automatically store and reuse a reference if we receive it. For example, existing recurring sequences will be enriched with a scheme reference as soon as one is received.

For merchants where the default attributes calculation described above is not sufficient (for example, where merchants have their own card storage in place), we provide API fields to allow this calculation to be overridden. These fields are only available when processing payments (including deferred payments) or account verification transactions via the API; it is not possible to override this information when using a hosted payment page or with subsequent recurring/instalment transactions using the REPEAT operation.

The merchant has responsibility for the accuracy of stored credential details when presenting in the API. Pay360 may override presented stored credential API fields, when required, to make a valid presentment for authorisation.

When overriding one or more Stored Credential attributes using the API fields above, if an invalid combination is supplied, the request will be rejected with response code V100 and a message describing the problem.

We return information about payment credential storage and reuse in our API responses and notifications. These largely mirror the request fields described above, and will be returned for payment (including deferred payments), account verification and subsequent recurring/instalment (REPEAT) transactions. The values are populated according to the final classification we determine, after taking into account any overrides from the request.