1. Generating the Hosted Page/iFrame
First, display a checkbox asking customers if they want to save their card to later trigger the installment(s) for a recurring payment.
Please refer to this article to generate the hosted payment page.
Please specify the following values:
Field name | Value |
orderid | Order ID example for the 1st installment: MYTESTORDER001-installment-1-of-3 |
eci | For an e-commerce transaction, set the value: 7 |
multi_use | In order to enable the “one-click” or recurring payment mode, set the value: 1 |
2. Saving the card token in your database
In the API response and server-to-server notification, you will receive the card information, including the card token. You should save the following data in your database:
Field name (in HTTP POST) | Description |
payment_product |
Payment product used to complete the transaction (e.g.: cb, bcmc, paypal) |
payment_method[token] | Card token |
payment_method[brand] | Card brand (e.g.: VISA, MASTERCARD, AMERICAN EXPRESS, MAESTRO) |
payment_method[pan] | Card number (up to 19 characters) Please note that, due to PCI DSS security standards, our system has to mask credit card numbers in any output (e.g.: 549619**4769). |
payment_method[card_holder] | Cardholder’s name |
payment_method[card_expiry_month] | Card expiry month (2 digits) |
payment_method[card_expiry_year] | Card expiry year (4 digits) |
payment_method[issuer] | Card issuing bank name Do not rely on this value to remain static over time. Bank names may change due to acquisitions and mergers. |
payment_method[country] | Bank country code where the card was issued This two-letter country code complies with ISO 3166-1 (alpha 2). |
3. Triggering payment for the installment(s)
For the next installment(s), you will have to use the WS “order” method, with the parameters below.
You should check the expiration date before triggering additional orders to avoid declined transactions. Please also inform your client each time you submit a new order.
Service endpoints
Environment | Endpoint |
---|---|
Stage |
|
Production |
Request parameters
Format abbreviation | Description |
AN | Alphanumeric characters (a-z, A-Z, 0-9) |
A | Alphabetic characters only (a-z, A-Z) |
N | Numeric characters only |
R | Decimal number with explicit decimal point, signed |
JSON | JavaScript Object Notation |
Payment settings
Field name | Format | Length | Description |
orderid | AN | 32 | Order ID example for the 2nd installment: MYTESTORDER001-installment-2-of-3 Then, for the 3rd and last installment, send a new request with a different order ID: MYTESTORDER001-installment-3-of-3 |
operation | A | - | Set the value: Sale = debits the customer immediately |
eci | N [string] | 1 | Set the value: 9 |
description | AN | 128 | Short description of the order |
long_description | AN | - | Additional description of the order |
payment_product | AN | 255 | Please check the list of alternative payment methods |
cardtoken | AN | - | This parameter is specific to credit or debit card payments. |
currency | A | 3 | Base currency for the order (default to EUR) This three-character currency code complies with ISO 4217. |
amount | R | - | Order total amount |
shipping | R | - | Shipping fees for the order (default to zero) Can be omitted if the shipping fees value is zero. |
tax | R | - | Tax amount for the order (default to zero) Can be omitted if the tax amount value is zero. |
tax_rate | R | - | Tax rate for the order |
custom_data | JSON | - | You can use this parameter to submit custom values you wish to show in HiPay’s back office transaction details, to receive back in the API response messages and in the notifications or to activate specific anti-fraud rules. E.g.: custom_data => { "shipping_method":"click and collect", "first_order":"0", "products_list":"First product, Second product, Third product"} |
Customer information
Field name | Format | Length | Description |
AN | - | Customer’s email address | |
phone | AN |
- | Customer’s phone number |
birthdate | N | 8 | Customer’s birthdate (YYYYMMDD) For fraud detection purposes |
gender | A | 1 |
Gender of the customer: M = male |
firstname | AN |
- | Customer’s first name |
lastname | AN | - | Customer’s last name |
streetaddress | AN | - | Customer’s street address |
streetaddress2 | AN | - |
Additional address information of the customer (e.g.: building, floor, flat, etc.) |
city | AN | - | Customer’s city |
state | AN | - | State of the country |
zipcode | AN | - | Zip or postal code of the customer |
country | A | 2 | Country code of the customer This two-letter country code complies with ISO 3166-1 (alpha 2). |
shipto_firstname | AN | - | First name of the order’s recipient |
shipto_lastname | AN | - | Last name of the order’s recipient |
shipto_streetaddress | AN | - | Street address where the order is to be shipped |
shipto_streetaddress2 | AN | - | Additional information about the street address where the order is to be shipped (e.g.: building, floor, flat, etc.) |
shipto_city | AN | - | City where the order is to be shipped |
shipto_state | AN | - | State where the order is to be shipped |
shipto_zipcode | AN | - | Zip or postal code where the order is to be shipped |
shipto_country | A | 2 |
Country code where the order is to be shipped This two-letter country code complies with ISO 3166-1 (alpha 2). |
ipaddr | AN | - | Customer’s IP address |
cid | AN | - | Unique customer ID |
accept_url | AN | - | URL to redirect your customers to once the payment process is completed successfully |
decline_url | AN | - | URL to redirect your customers to after the acquirer has declined the payment |
pending_url | AN | - | URL to redirect your customers to when the payment request has been submitted to the acquirer, but the response is not available yet |
exception_url | AN | - | URL to redirect your customers to after a system failure |
cancel_url | AN | - | URL to redirect your customers to when they decide to abort the payment |
Comentários
0 comentário
Artigo fechado para comentários.