Menu

Stored Credential Transactions

IPS V3.1.2.0
Released August 2021

Stored Credentials are an online verification method.

Stored Credentials works by issuing a payment token for future payments with a reference to a current transaction. Examples are payment by installments, recurring payments or pay-as-you-go.

Modes

The modes we support are Recurring and Unscheduled.

For both modes:

  1. Create a token using the Sale transaction to place an AVR (Account Verification) request for the appropriate token purpose - that is Recurring or Unscheduled mode.

  2. Charge the token using the Sale transaction request with the appropriate token purpose.

Integration notes

To use the Stored Credentials features you must opt for token services. Contact your Worldpay from FIS Relationship Manager or Support for information.

  • You need a dedicated MID for Recurring transactions. To get a dedicated MID, contact your FIS Worldpay Relationship Manager or Support

  • Only tokens generated from an AVR request with a token purpose may be used in a follow up request to charge the token

    POS should store these types of token (provided in the AVR request response) along with their token purpose (given in the AVR request). POS will use them with the same token purpose when needed for a follow up recurring or unscheduled transaction

  • Stored Credentials are currently valid only for Visa and Mastercard

    For other card schemes such as American Express, Diners, or JCB you can use the tokens provided from a normal Sale transaction without Stored Credential identifiers to charge the token.

  • For a better user experience we recommend that you implement a Check Card using the Sale transaction. This is to confirm the card scheme is Visa or Mastercard as the first part of your transaction flow. This flow is to generate a token for use with Stored Credentials (see the Check Card section below for details)

The payment cycle

The payment cycle is:

  1. Optional: Implement a Sale transaction with the Checkcard payment type to validate the card scheme.

  2. Authorise the card – make the Account Verification Request (AVR)

    • This is where you validate the card and indicate your intent to use it for merchant initiated transactions

    • Flag the intent - Recurring or Unscheduled, with the token purpose in the IPS API

    • If approved, you receive the card token in the transaction response. The token is created with scheme reference data attached to it in the FISGlobal platform. The scheme reference data shows the difference between tokens created through the AVR request and tokens created through other transactions. Note that in IPS 3.1.2.0 we do not return the scheme reference data in the transaction response – this will change in later versions.

  3. Store the token and its token purpose for subsequent use.

  4. When needed, retrieve the token and its token purpose, implement a Sale with Token request, and provide the associated token purpose.

Payment flow example

An example of the flow is:

  1. Check the card with the payment type check-card-payment.

  2. Check if the response value in the applicationLabel field indicates Visa or Mastercard

  3. If the response value is Visa or Mastercard, continue and place an AVR request. Receive the response - this response contains the token.

  4. If response value is not Visa or Mastercard, then abort the transaction.

For other schemes such as Amex, Diners, and JCB, you can use the tokens provided from a normal Sale transaction without Stored Credential identifiers.

There is no transaction approval from the issuer for a Check Card transaction.

Sale transaction for Account Verification (AVR)

Account Verification Request (AVR) is an online verification method.

It works by issuing a payment token for future payments with a reference to a current transaction. Supported modes are recurring payments and unscheduled payments.

AVR request flow for a chip card

The diagram below shows the AVR request flow for Chip Card:

AVR Request for chip card

Note: The blue colour shows the progress messages exchanged between IPS and the EPOS application. The black colour shows the data exchange between these applications.

The sequence in the above diagram is below. The number of the step corresponds to the number of the arrow in the diagram.

  1. Sale transaction request for Account Verification for a chip card:

    Copied!
    {
    "paymentType": "sale",
    "merchantTransactionReference": "MS123A54B3DF",
    "instruction": {
    "value": {
    "amount": 0
    },
    "narrative": {
    "line1": "Transactiondescription"
    },
    "paymentInstrument": {
    "type": "card/present",
    "isHandledOnline": true,
    "tokenPurpose": "unscheduled"
    }
    }
    }
  2. Please Wait Notification: Message send to EPOS Please wait.

  3. Process Request as AVR: Process request for AVR.

  4. Display Insert/Swipe Card: Display Insert/Swipe Card text on PED screen.

  5. Notification for Insert/Swipe Card: Message send to EPOS PLEASE INSERT/SWIPE CARD.

  6. Please Wait Notification: Message send to EPOS Please wait.

  7. Enter PIN Notification: Message send to EPOS ENTER PIN.

  8. Enter PIN on PED: Enter PIN on PED.

  9. PIN Ok Notification: Message send to EPOS PIN OK.

  10. Send Auth Request: Authorisation request processing.

  11. Authorizing Notification: Message send to EPOS Authorising...

  12. Authorization Response: Authorisation response received.

  13. CARD ACCOUNT VALID Notification: Message send to EPOS is CARD ACCOUNT VALID.

  14. Capture Bypass: Bypass capture.

  15. Please Remove Card Notification: Message send to EPOS is PLEASE REMOVE CARD.

  16. Sent Merchant and Customer receipts: Send Merchant and Customer Receipts to EPOS.

  17. Sent Response data: Send receipt and response data to EPOS.

  18. Transaction Complete Notification: Transaction Completed.

Sale transaction request for a swipe card

The diagram shows the AVR request flow for a swipe card.

AVR Request for a swipe card

Note: The blue colour shows the progress messages exchanged between IPS and the EPOS application. The black colour shows the data exchange between these applications.

The sequence in the diagram is below. The number of the step corresponds to the number of the arrow in the diagram.

  1. Sale Transaction Request for Account Verification For Swipe Card:

    Copied!
    {
     "paymentType": "sale",
     "merchantTransactionReference": "MS123A54B3DF",
     "instruction": {
     "value": {
     "amount": 0
     },
     "narrative": {
     "line1": "Transactiondescription"
     },
     "paymentInstrument": {
     "type": "card/present",
     "isHandledOnline": true,
     "tokenPurpose": "unscheduled"
     }
     }
  2. Please Wait Notification: Message send to EPOS Please wait.

  3. Process Request as AVR: Process request for AVR.

  4. Display Insert/Swipe Card: Display Insert/Swipe Card text on PED screen.

  5. Notification Insert/Swipe Card: Message send to EPOS PLEASE INSERT/SWIPE CARD.

  6. Swipe Card Notification: Message send to EPOS SWIPE: PLEASE WAIT.

  7. Send Auth Request: Authorisation request processing.

  8. Authorizing Notification: Message send to EPOS Authorising...

  9. Authorization Response: Authorisation response received.

  10. Send Accept/Reject: Message send to EPOS Accept/Reject signature on Receipt.

    Copied!
    {
    "requestType":"SIGNATURE_VERIFICATION",
    "userMessage":"AUTH CODE:017736, Is Signature Ok?",
    "acquirerMid":null,
    "acquirerContactNumber":null,
    "messageBody":null,
    "maximumCashbackLimit":0,
    "cvvResult":null,
    "addressResult":null,
    "zipResult":null
    }
  11. Send Merchant Receipt data: Send Merchant Receipt data to EPOS.

  12. Accept/Reject received from EPOS:

    Accept Case: If the merchant accepts the signature then IPS receives this message below from EPOS:

    {"merchantTransactionReference":"MS_123-A54B3DF","data":{"action":"signature-verification","isSignatureVerified":true }}

    Reject Case: If the merchant rejects the signature then IPS receives this message from EPOS :

    {"merchantTransactionReference":"MS_123-A54B3DF","data":{"action":"signature-verification","isSignatureVerified":false }}

  13. CARD ACCOUNT VALID Notification: Message sent to EPOS CARD ACCOUNT VALID.

  14. Capture Bypass: Bypass capture.

  15. Send Customer Receipt data: Send customer receipt data to EPOS.

  16. Send Response data: Send response data.

  17. Transaction Complete notification: Transaction is complete.

The following changes and validation are applicable:

  • The Transaction Type is Sale

  • The amount in the request must be zero

  • The Transaction Purpose should be either Recurring or Unscheduled

  • The AVR request can only be made online

  • If the system is offline IPS declines as an Offline Decline transaction

  • If the AVR transaction is successfully approved then a Card account valid message is sent on the Notification channel

Sale transaction to charge the token

The diagram below shows the charge token request flow. This flow occurs when you have a token with stored credential identifiers, that is, generated from the AVR request.

Charge token request flow

Note: The blue colour shows the progress messages exchanged between IPS and the EPOS application. The black colour shows the data exchange between these applications.

The sequence in the diagram is below. The number of the step corresponds to the number of the arrow in the diagram:

  1. Sale transaction to Charge the Token Request:

    Copied!
    {
     "paymentType": "sale",
     "merchantTransactionReference": "MS123A54B3DF",
     "instruction": {
     "value": {
     "amount": 1099
     },
     "narrative": {
     "line1": "Transactiondescription"
     },
     "paymentInstrument": {
     "type": "card/token",
     "tokenId":"99545454087869885454",
     "isHandledOnline": true,
     "tokenPurpose": "unscheduled"
     }
     }
     }
  2. Please Wait Notification: Message send to EPOS Please wait.

  3. Send Charge EPOS Transaction Request: Send Charge EPOS Transaction Request.

  4. Authorisation Response: Authorisation response received.

  5. Approved Notification: Message send to EPOS APPROVED.

  6. Send Merchant and Customer Receipt: Send Merchant and Customer receipt data to EPOS.

  7. Send Response data: Send response data to EPOS.

  8. Transaction Complete Notification: Transaction Completed.

Transaction Request Validation for Charge Token

  • The transaction type is Sale

  • The transaction Purpose should be either Recurring or Unscheduled

  • If the Charge Token request is successfully approved then an Approved message is sent on the Notification channel

  • If the Charge Token transaction is declined than a Declined message is sent on the Notification channel

Code Examples

This section gives the code for a selection of transaction types.

Sale: Card Present AVR request for Unscheduled purpose.

Request:

Copied!
{
"paymentType": "sale",
"merchantTransactionReference": "MS123A54B3DF",
"instruction": {
"value": {
"amount": 0
},
"narrative": {
"line1": "Transactiondescription"
},
"paymentInstrument": {
"type": "card/present",
"isHandledOnline": true,
"tokenPurpose": "unscheduled"
}
}
}

Response:

Copied!
{
 "payments": [
   {
     "paymentType": "sale",
     "transactionDateTime": "2021-08-05T05:26:45.716Z",
     "result": "authorised-online",
     "merchant": {
       "merchantId": "21249872",
       "name": "YESpay Demo                            ",
       "address": {
         "line1": "153 Checknet House",
         "line2": "East Barnet Road",
         "city": "Barnet",
         "state": ",",
         "postalCode": "EN4 8QQ"
       }
     },
     "paypoint": {
       "paypointId": "INS12",
       "terminalId": "22980011"
     },
     "value": {
       "amount": 0
     },
     "merchantTransactionReference": "MS_123-A54B3DF",
     "eftSequenceNumber": 11,
     "retrievalReferenceNumber": 11,
     "receiptNumber": 11,
     "receiptRetentionReminder": "PLEASE KEEP THIS RECEIPT FOR YOUR RECORDS",
     "receiptCustomerDeclaration": "YOU WILL NOT BE CHARGED FOR THIS TRANSACTION",
     "paymentInstrument": {
       "type": "card/present",
       "card": {
         "tokenId": "99545454087869885454",
         "cardNumber": "545454XXXXXX5454",
         "expiryDate": {
           "month": 12,
           "year": 21
         },
         "issuerCode": "mastercard",
         "countryCode": "826",
         "applicationLabel": "MasterCard",
         "applicationEffectiveDate": "1999-12-30"
       },
       "posEntryMode": "integrated-circuit-chip",
       "cardVerificationMethod": "signature"
     },
     "outcome": "succeeded"
   }
 ]
}

Sale: Charge Token request for Unscheduled purpose

Request:

Copied!
{
"paymentType": "sale",
"merchantTransactionReference": "MS123A54B3DF",
"instruction": {
"value": {
"amount": 1099
},
"narrative": {
"line1": "Transactiondescription"
},
"paymentInstrument": {
"type": "card/token",
"tokenId":"99545454087869885454",
"isHandledOnline": true,
"tokenPurpose": "unscheduled"
}
}
}

Response:

Copied!
{
 "payments": [
   {
     "paymentType": "sale",
     "transactionDateTime": "20210805T06:25:04.836Z",
     "result": "authorised-online",
     "merchant": {
       "merchantId": "21249872",
       "name": "YESpay Demo                            ",
       "address": {
         "line1": "153 Checknet House",
         "line2": "East Barnet Road",
         "city": "Barnet",
         "state": ",",
         "postalCode": "EN4 8QQ"
       }
     },
     "paypoint": {
       "paypointId": "INS12",
       "terminalId": "22980011"
     },
     "value": {
       "amount": 1099,
       "currencyCode": "GBP"
     },
     "merchantTransactionReference": "MS123A54B3DF",
     "gatewayTransactionReference": "PGTR1000277899",
     "eftSequenceNumber": 12,
     "retrievalReferenceNumber": 12,
     "receiptNumber": 12,
     "receiptRetentionReminder": "PLEASE KEEP THIS RECEIPT FOR YOUR RECORDS",
     "receiptCustomerDeclaration": "PLEASE DEBIT MY ACCOUNT",
     "paymentInstrument": {
       "type": "card/token",
       "card": {
         "tokenId": "99545454087869885454",
         "expiryDate": {
           "month": 12,
           "year": 99
         },
         "applicationLabel": "MasterCard",
         "applicationEffectiveDate": "1999-12-30"
       },
       "posEntryMode": "cardholder-not-present",
       "authorisation": {
         "authorisationCode": "000C10"
       }
     },
     "outcome": "succeeded"
   }
 ]
}

Check card followed by Sale Transaction for Account Verification (AVR) scenarios

  • Start the check-card-payment request. Then wait for a defined time for the follow up request. If we send no other request then the transaction will cancel/abort

  • Start the check-card-payment request. Then wait for defined time for the follow up request. If we send another request which has either a different MTR or a different payment instrument, then the transaction will cancel/abort

  • Start the check-card-payment request. Then wait for defined time for the follow up request. If we send a sale transaction request with or without a token purpose with an amount > 0 then the sale transaction occurs

  • Start the check-card-payment request. Then wait for defined time for the follow up request. If we send a Sale transaction for Account Verification Request, then it proceeds successfully as an AVR transaction

  • Start the check-card-payment request. Then wait for defined time for the follow up request. If we send Sale transaction for Account Verification Request without a token purpose then the transaction will cancel/abort

  • Start the check-card-payment request with a token purpose - it will make a check-card-payment transaction

  • Start the check-card request with a token purpose - it will make a check-card transaction

  • Start the check-card-payment request and tap the card after that. IPS wait for a defined time for the follow up request. If we send an AVR request then transaction will cancel/abort. The reason for this cancel/abort is it is a contactless transaction, and in AVR we do not support contactless transactions