User Pay Interface¶
Version 1.1
October 10, 2019
Table of Contents
Section Revision History¶
Revision 14.01 Jan 14, 2014
- Interface document created
Revision 19.10 Oct 10, 2019
- Published in document web
Introduction¶
Eligible merchants are permitted to assess a web payment fee to accept credit and debit cards as a form of payment. Cardholders must be notified of the fee at the time of payment and be given the opportunity to opt out of the sale.
The following functionality is supported for the User Pay Fee Interface:
- Web payment fees can be assessed by establishing different rates by card type or card product
- Separate charges can be processed for the fee and payment amounts
- Transactions can be processed using either tokens or card numbers
- CVV & AVS authentication can be included when authorizing the amounts to be charged to the cardholder
To minimize customer service inquires, the web payment fee charged must be processed as a separate and unique transaction and cannot be included in the total amount for the product or service paid for.
Processing Flow¶
Caledon’s User Pay interface is based on a two-step process where the fee amount is calculated first followed by the processing of the payment.
Example of processing flow:
- Invoice/bill amount to be paid is determined by the merchant application
- Merchant sends a request to Caledon’s server to determine the amount of the fees to be paid by the cardholder
- The fee amount is calculated by Caledon and the response is returned to the Merchant’s server
- The fee amount and total to be paid is to be presented to the cardholder for their approval
- Cardholder enters their card information or a token can be selected which is to be used for payment
- The payment request is sent to Caledon for authorization
- Response is returned to the Merchant’s server indicating whether the transaction(s) has been approved or declined
The processing flow may vary based on the functionality being implemented or to simplify integration with the merchant’s existing processes.
Integration Interface¶
The sections included below provide details on the fields supported for each of the request and response messages.
HTTPS POST method is to be used for all requests submitted via Caledon’s User Pay interface.
For implementations where rates vary based on card type or card product, the Fee Calculation Request message must provide information on the card to be used for payment, i.e., card type, card product, card number or token must be specified.
Processing of separate charges for payment amount and fee amount is handled automatically by Caledon based on the configuration options. Only one Payment Processing Request message is to be sent by the merchant’s application, which will include the payment amount and fee amount.
Convenience Fee Calculation Request¶
| Field Name | Length | Type | Req | Description |
|---|---|---|---|---|
| type | 1 | Value of ‘C’ to specify calculation request | Y | Used to indicate the type of request message |
| terminal_Id | 8 | A/N | Y | Terminal ID assigned by Caledon |
| fee_reference_number | 30 | A/N Valid values: A-Z a-z 0-9 - / \ |
Y | Unique reference number associated with the fee calculation request |
| card_product | 2 | A Values to be used for card type: VC - Visa MC - MasterCard Values to be used for card product: VC - Visa credit VD - Visa debit VB - Visa business MC - MasterCard credit MD - MasterCard debit MB - MasterCard business |
O | Used to indicate the card type or card product to be used for payment. This field is not required if the same rate applies for all card types. If difference rates are setup by card type or card product then this field is required. |
| card_number | 16 | N If card number is included then the value must be numeric; no spaces or hyphens are allowed |
O | This field may contain the card number that will be used to process the payment |
| expiry_date | 4 | N If expiry date is included then the format must be MMYY |
O | If a card number has been provided then this field must contain the expiry date of the card |
| token | 30 | A/N Allowed characters: 0-9 A-Z : @ | - + / , _ Lower case letters will be converted to upper case |
O | This field may contain the token to be used to process the payment. This field must be blank if a card number and expiry date have been provided. |
| amount | 10 | N 10 numeric characters with 2 implied decimals $1000.00 becomes ‘100000’ |
Y | Used to specify the bill/invoice payment amount |
Convenience Fee Calculation Response¶
| Field Name | Length | Type | Req | Description |
|---|---|---|---|---|
| type | 1 | Value of ‘C’ to specify calculation request | Y | Specifies the type of request message |
| terminal_Id | 8 | A/N | Y | Terminal ID assigned by Caledon |
| fee_reference_number | 30 | A/N Valid values: A-Z a-z 0-9 - / \ |
Y | Unique reference number associated with the fee calculation request |
| card_product | 2 | A Values to be used for card type: VC - Visa MC - MasterCard Values to be used for card product: VC - Visa credit VD - Visa debit VB - Visa business MC - MasterCard credit MD - MasterCard debit MB - MasterCard business |
Conditional | This field will be populated if a value was included in the request or different rates are setup by card type/product. |
| amount | 10 | N 10 numeric characters with 2 implied decimals $1000.00 becomes ‘100000’ |
Y | The bill/invoice payment amount as specified in the request message |
| fee_amount | 8 | N 8 numeric characters with 2 implied decimals $1000.00 becomes ‘100000’ |
Y | The fee amount calculated based on the requested card type/product and payment amount |
| total_amount | 10 | N 10 numeric characters with 2 implied decimals $1000.00 becomes ‘100000’ |
Y | The total amount to be charged to the card |
| response_code | 4 | A/N Values are: ‘0000’ - success ‘C001’ - invalid type ‘C002’ - invalid terminal id ‘C003’ - invalid reference number ‘C004’ - invalid card product ‘C005’ - invalid amount ‘C006’ - only card or token allowed ‘C007’ - invalid card number ‘C008’ - invalid expiry date ‘C011’ - invalid token ‘C999’ - Service unavailable |
Y | The response code specifying the result of the fee calculation request |
| response_text | 10 | A Values are: ‘Success’ if the request was successful ‘Rejected’ if there were validation errors |
Y | This field provides text indicating the outcome of fee calculation request |
Payment Processing Request¶
| Field Name | Length | Type | Req | Description |
|---|---|---|---|---|
| type | 1 | A Valid values are: ‘P’ to specify payment request ‘V’ to void a previous payment request Payment requests can only be voided if the transaction has not been settled. |
Y | Used to indicate the type of request message |
| terminal_Id | 8 | A/N | Y | Terminal ID assigned by Caledon |
| fee_reference_number | 30 | A/N Valid values: A-Z a-z 0-9 - / \ |
Y | The reference number of the convenience fee calculation request. If this reference number does not match the convenience fee calculation request then the payment request will be rejected. |
| reference_number | 60 | A/N Valid values: A-Z a-z 0-9 - / \ |
Y | The reference number of the payment request |
| card_product | 2 | A Values to be used for card type: VC - Visa MC - MasterCard Values to be used for card product: VC - Visa credit VD - Visa debit VB - Visa business MC - MasterCard credit MD - MasterCard debit MB - MasterCard business |
Conditional | Used to indicate the type of card to be used for payment |
| card_number | 16 | N No spaces, dashes, hyphens or any other punctuation are allowed |
Optional | The card number that will be used to process the payment. This field is required if type = ‘P’ and a token is not provided. Card number is not required if a void (type=V) is being processed. |
| expiry_date | 4 | N If expiry date is included then the format must be MMYY |
Optional | The expiry date of the card. This field is required if type = ‘P’ and a token is not provided. Expiry date is not required if a void (type=V) is being processed. |
| token | 30 | A/N Allowed characters: 0-9 A-Z : @ | - + / , _ Lower case letters will be converted to upper case |
Optional | Token ID to be used for processing of the payment. Token must be provided if type=’P’ and the card number and expiry date are not included. Token is not required if a void (type=V) is being processed |
| cvv | 4 | N | Optional | 3 or 4 character value printed on the front or back of a card. Also known as security code, cvv is used for authentication of the card being presented for payment. Inclusion of this field is recommended for the processing of an initial payment - recurring payment flag set to N |
| postal_code | 10 | A/N No spaces, dashes, hyphens allowed |
Optional | The postal/zip code of the cardholder’s billing address which is to be used for authentication |
| amount | 10 | N 10 numeric characters with 2 implied decimals $1000.00 becomes ‘100000’ |
Y | Payment amount excluding fees |
| fee_amount | 8 | N 8 numeric characters with 2 implied decimals $1000.00 becomes ‘100000’ |
Y | Fee amount as received in the fee calculation response |
| total_amount | 10 | N 10 numeric characters with 2 implied decimals $1000.00 becomes ‘100000’ |
Y | The total amount to be charged to the card |
| recurring_flag | 1 | A/N Values are: ‘Y’ - Recurring payment ‘N’ - First initial payment |
Optional | This flag indicates whether a transaction is an initial or recurring payment Recurring flag is not required for processing of voids (type=V). |
Note: The amount, fee amount and total amount in the payment request must match the fee calculation response otherwise a mismatch error will be returned.
Payment Processing Response¶
| Field Name | Length | Type | Req | Description |
|---|---|---|---|---|
| type | 1 | A Value of: ‘P’ to specify payment request ‘V’ for void response |
Y | Used to indicate the type of request message |
| terminal_Id | 8 | A/N | Y | Terminal ID assigned by Caledon |
| fee_reference_number | 30 | A/N Valid values: A-Z a-z 0-9 - / \ |
Y | The reference number of the convenience fee calculation request |
| reference_number | 60 | A/N Valid values: A-Z a-z 0-9 - / \ |
Y | The reference number of the payment request |
| card_product | 2 | A Values to be used for card type: VC - Visa MC - MasterCard Values to be used for card product: VC - Visa credit VD - Visa debit VB - Visa business MC - MasterCard credit MD - MasterCard debit MB - MasterCard business |
Conditional | Type of card used for payment as specified in the request |
| card_number | 4 | N Last 4 digits of the card number |
Optional | The masked card number that was used to process the payment. |
| expiry_date | 4 | N The expiry date in the form MMYY |
Optional | The expiry date of the card |
| token | 30 | A/N Allowed characters: 0-9 A-Z : @ | - + / , _ Lower case letters will be converted to upper case |
Optional | The token, which was used to process the payment. This field will be blank if a card number was used in place of a token |
| amount | 10 | N 10 numeric characters with 2 implied decimals $1000.00 becomes ‘100000’ |
Y | Payment amount excluding fees |
| fee_amount | 8 | N 8 numeric characters with 2 implied decimals $1000.00 becomes ‘100000’ |
Y | Fee amount as received in the fee calculation response |
| total_amount | 10 | N 10 numeric characters with 2 implied decimals $1000.00 becomes ‘100000’ |
Y | The total amount to be charged to the card |
| response_code | 4 | A/N Values are ‘0000’ - success ‘C001’ - invalid type ‘C002’ - invalid terminal id ‘C003’ - invalid reference number ‘C004’ - invalid card product ‘C005’ - invalid amount ‘C006’ - invalid fee amount ‘C007’ - invalid total amount ‘C008’ - invalid recurring payment flag ‘C009’ - card product mismatch ‘C010’ - amount mismatch ‘C011’ - fee amount mismatch ‘C012’ - payment total mismatch ‘C013’ - only card or token allowed ‘C014’ - void unsuccessful ‘C015’ - invalid card_number ‘C016’ - invalid expiry_date ‘C017’ - invalid postal_code ‘C018 - invalid cvv ‘C019’ - invalid token ‘C999’ - Service unavailable |
Y | This field contains a 4 character result code |
| fee_response | A/N Values are: This field may be blank for the following conditions: payment request was rejected due to validation errors payment and fee amount are being processed as a single transaction payment amount was declined Authorization code will be provided if the fee amount was approved Decline message will be provided if the fee amount was declined |
Conditional | This field contains the authorization code, decline message or void confirmation for the fee amount | |
| payment_response | A/N Values are: This field will be blank if the payment request was rejected due to validation errors. Authorization code will be provided if the payment amount was approved Decline message will be provided if the payment amount was declined |
This field contains the authorization code, decline message, or void confirmation for the payment amount. |
Examples¶
Examples provided below are shown based on cURL command line interface.
Convenience fee calculation¶
Request:
curl -d type=C \
-d terminal_id=CONVTEST \
-d fee_reference_number=98544JLL \
-d amount=100000 \
https://portal.caledoncard.com/convfee/
Response:
type=C&terminal_id=CONVTEST&fee_reference_number=98544JLL&amount=100000&fee_amount=2000&
total_amount=102000&response_code=0000&response_text=success
Payment processing¶
Request:
curl -d type=P \
-d terminal_id=CONVTEST \
-d fee_reference_number=98544JLL \
-d reference_number=98765432 \
-d card_number=5550000000000003 \
-d exp=1214 \
-d cvv=258 \
-d postal_code=L9K8K8 \
-d amount=100000 \
-d fee_amount=2000 \
-d total_amount=102000 \
-d recurring_flag=N \
https://portal.caledoncard.com/convfee/
Response:
type=P&terminal_id=CONVTEST&fee_reference_number=98544JLL&reference_number=98765432&
card_number=************0003&exp=1214&amount=100000&fee_amount=2000&total_amount=102000&
response_code=0000&fee_response=T12345&payment_response=12345A