Use Multiple Payment Sources
You must provide payment details for card payments in several API requests. For example, PAY or AUTHORIZE. You can specify these payment details, such as card number, card expiry, and card security code (CSC), using one or more of the following payment sources:
- Request fields: Payment details are specified directly in the request.
- Session: Payment details are stored against a payment session.
- Card token: Payment details are stored in a secure repository against a token if using tokenization.
Precedence rules
If a payment detail, for example, card number is provided more than once in a single request because it is contained in two or more payment sources, the following precedence rules determine the source used:
- API request fields
- Session
- Card token
In other words, data contained in the API request fields overrides the data stored against the session and token details, and session data overrides the token details. For example, a session ID refers to a session that contains the card number, card expiry, and CSC. A token contains the card number and card expiry. If you include both a session ID and a token in a PAY request, the card details specified in the session are used in the transaction.
Example 1: Usage of both token and session
You want to submit a PAY request using the card number and expiry date stored in a token and the CSC collected in a session. The following example request shows how to provide both the token and session sources in the request.
| HTTP Method | PUT |
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/<version>/merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID> |
| JSON |
{
"apiOperation": "PAY",
"session": {
"id": "SESSION000177777777777777777777"
},
"sourceOfFunds": {
"token": "9999999999999999"
},
"order": {
"amount": "34.00",
"currency": "AUD"
}
}
|
The preceding JSON assumes that:
- A session with the
SESSION000177777777777777777777session ID was previously created and contains the CSC. - A token with the
9999999999999999token ID was previously stored and contains the card number and expiry date.
Example 2: Token update for expiry date
You want to update the expiry date on a stored token using the CREATE OR UPDATE TOKEN request, but you want to leave the card number unchanged. The token you provide in the request URL identifies the token that you want to update. Providing this same token as a source of payment details causes your previously stored details to be reused. This means that you do not need to recapture the payment details. If you provide the new expiry date in the sourceOfFunds.provided.card object of the request, that value overrides the expiry date already stored in the token.
The following example request shows how to provide both payment details and token sources using the CREATE OR UPDATE request.
| HTTP Method | PUT |
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/<version>/merchant/<merchant_ID>/token/9999999999999999 |
| JSON |
{
"sourceOfFunds": {
"provided": {
"card": {
"expiry": {
"month": "05",
"year": "13"
},
"token": "99999999999999"
}
},
"type": "CARD"
}
}
|
The preceding JSON assumes that a token with the 9999999999999999 token ID was previously stored and contains a card number and expiry date.
The result of this operation is that the 9999999999999999 token now has an expiry date of 05/13 and the card number remains unchanged.