Using Multiple Sources of Payment Details
When performing a number of Spring by Citi Payment GatewayAPI calls (for example, Pay, Authorize, Refund, Capture, Save, Initiate Authentication, Authenticate Payer), card details must be provided. These payment details may be specified using a number of "sources".
Supported Sources
- Request Fields: Payment details specified directly in the request (e.g. card number, card expiry, card security code).
- Session: Payment details stored against a Payment Session.
- Card Token: Payment details stored in a secure repository against a token (if using Tokenization).
Precedence Rules
If a card detail, for example, card number, is provided more than once in a single request because it is contained in two or more sources, precedence rules will determine the source used. The order of precedence is as follows:
- API Request Fields
- Session Identifier
- Card Token
That is to say, data contained in the API request fields will override data stored against the session which will override token details.
For example, if you include both a session identifier (which contains the card number, card expiry and CSC) and token (which contains the card number and card expiry) in a Pay request, then, based on the order of precedence, the card details specified in the session identifier will be used in the financial transaction.
Source of Funds API Reference[REST][NVP]
Examples
You may specify the payment details using one, or a combination, of these sources.
Perform transaction with details from token and session
You want to submit a Pay operation 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 token and session sources in the Pay request:
| HTTP Method | PUT |
| URL | https://na.gateway.spring.citi.com/api/rest/version/72/merchant/<merchant>/order/<orderId>/transaction/<transactionId> |
| JSON |
{
"apiOperation": "PAY",
"session": {
"id": "SESSION000177777777777777777777"
},
"sourceOfFunds": {
"token": "9999999999999999"
},
"order": {
"amount": "34.00",
"currency": "AUD"
}
}
|
The above JSON assumes:
- A session with an identifier "SESSION000177777777777777777777" was previously created and contains the CSC.
- A token with an identifier "9999999999999999" was previously stored and contains the card number and expiry date.
Update a token with new expiry date
You want to update the expiry date on a stored token using the Tokenization operation (but leave the card number unchanged). The token you supply in the request URL identifies the token you wish to update. Supplying this same token as a source of payment details will cause your previously stored details to be reused. This means that you do not need to recapture the card number. If you provide the new expiry date in the Card Details section of the request, that value will override the expiry date already stored in the token (see Precedence Rules).
The following example request shows how to provide both payment details and token sources using the Tokenization operation:
| HTTP Method | PUT |
| URL | https://na.gateway.spring.citi.com/api/rest/version/72/merchant/<merchant>/token/9999999999999999 |
| JSON |
{
"sourceOfFunds": {
"provided": {
"card": {
"expiry": {
"month": "05",
"year": "13"
},
"number": "5123456789012346"
}
},
"type": "CARD"
}
}
|
The above JSON assumes:
- A token with id "9999999999999999" was previously stored and contains a card number and expiry date.
The result of this operation will be that token "9999999999999999" now has an expiry date of 05/13 (the card number remains unchanged).