If you want your customers to be redirected from your website directly to the alternative payment method page without going through the HiPay hosted payment page, you are in the right place.
Access a wide range of alternative payment methods (e.g.: PayPal, SOFORT, Mooney...) so that your customers can make purchases in their preferred currency with the payment method of their choice.
Service endpoints
There are two endpoints (base URLs) to which you can make your API calls:
- Stage, if you are testing your integration, and Production, when you have finished testing and want your application to go live.
| Environment | Endpoint |
|---|---|
|
Stage |
|
|
Production |
Request parameters
(For further details, please refer to the technical documentation.)
| 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 |
| Field name | Format | Length | Description |
|---|---|---|---|
| language | AN | 5 | Set the language of the alternative payment page. Locale code, default to en_GB – English – Great Britain E.g.: fr_FR, es_ES, etc. |
| Field name | Format | Length | Description |
|---|---|---|---|
| orderid | AN | 32 | ID of the order |
| operation | A | - | Set the value: Sale = debits the customer immediately |
| eci | N [string] | 1 | Set the value: 7 |
| description | AN | 128 | Short description of the order |
| long_description | AN | - | Additional description of the order |
| payment_product | AN | 255 |
Please check the list below:
|
| 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"} |
| 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 Mandatory for Bancontact (Only "BE") |
| 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 |
Full PHP example:
$data = array(
// Language setting
"language"=> "en_GB",
// Order information
"orderid"=> "HP".rand(microtime(0),100000),
"operation"=> "sale",
"eci"=> "7",
"description"=> "Description of the order",
"long_description"=> "Long description of the order",
"payment_product"=> "postfinance-card",
"currency"=> "CHF",
"amount"=> 100,
"shipping"=> 10,
"tax"=> 15,
"tax_rate"=> 15,
"custom_data"=>
'{
"shipping_method":"click and collect",
"first_order":"0",
"products_list": "First product, Second product",
"_reporting_data_1":"my custom data 1",
"_reporting_data_2":"my custom data 2",
"_reporting_data_3":"my custom data 3",
"_reporting_data_4":"my custom data 4",
"_reporting_data_5":"my custom data 5"
}',
// Customer information
"email"=> "jane.doe@test.com",
"gender"=> "M",
"firstname"=> "Jane",
"lastname"=> "Doe",
"birthdate"=> 19890525,
"phone"=> "01234567890",
"streetaddress"=> "Mingerstrasse 6",
"streetaddress2"=> "Bâtiment 1",
"city"=> "Berne",
"zipcode"=> "3014",
"country"=> "CH",
"shipto_firstname"=> "Jane",
"shipto_lastname"=> "Doe",
"shipto_streetaddress"=> "Mingerstrasse 6",
"shipto_streetaddress2"=> "Bâtiment 2",
"shipto_city"=> "Berne",
"shipto_zipcode"=> "3014",
"shipto_country"=> "CH",
"ipaddr"=> "127.0.0.1",
"cid"=> "123456",
"accept_url"=> "https://example.com/accept",
"decline_url"=> "https://example.com/decline",
"pending_url"=> "https://example.com/pending",
"exception_url"=> "https://example.com/exception",
"cancel_url"=> "https://example.com/cancel",
);
Response API JSON example:
{
"state":"forwarding",
"reason":"",
"forwardUrl":"https:\/\/stage-secure-gateway.hipay-tpp.com\/gateway\/forward\/537e9f1ccb6a50fcca830fc1343f3298",
"test":"true",
"mid":"00001234567",
"attemptId":"1",
"authorizationCode":"",
"transactionReference":"800004137998",
"dateCreated":"2019-08-29T15:24:27+0000",
"dateUpdated":"2019-08-29T17:24:28+0200",
"dateAuthorized":"",
"status":"142",
"message":"Authorization Requested",
"authorizedAmount":"0.00",
"capturedAmount":"0.00",
"refundedAmount":"0.00",
"creditedAmount":"0.00",
"decimals":"2",
"currency":"CHF",
"ipAddress":"0.0.0.0",
"ipCountry":"",
"deviceId":"",
"avsResult":"",
"cvcResult":"",
"eci":"7",
"paymentProduct":"postfinance-card",
"paymentMethod":"",
"threeDSecure":"",
"fraudScreening":
{
"scoring":"30",
"result":"ACCEPTED",
"review":""
},
"order":
{
"id":"HP1065",
"dateCreated":"2019-08-29T15:24:27+0000",
"attempts":"1",
"amount":"100.00",
"shipping":"10.00",
"tax":"15.00",
"decimals":"2",
"currency":"CHF",
"customerId":"123456",
"language":"en_EN",
"email":"jane.doe@test.com"
},
}
To consider a pending payment meaning the customer arrived on the payment page and is filling in the fields now, it is appropriate to rely on the server-to-server notification containing the following values:
status=142
message=Authorization+Requested
You can receive the server-to-server notification in:
- POST "application/x-www-form-urlencoded" format
- POST XML
POST pending server-to-server notification example:
state=forwarding
&test=true
&mid=00001234567
&attempt_id=1
&authorization_code=
&transaction_reference=800004137998
&date_created=2019-08-29T15%3A24%3A27%2B0000
&date_updated=2019-08-29T15%3A24%3A28%2B0000
&date_authorized=
&status=142
&message=Authorization+Requested
&authorized_amount=100.00
&captured_amount=0.00
&refunded_amount=0.00
&decimals=2
¤cy=CHF
&ip_address=0.0.0.0
&ip_country=
&device_id=
&custom_data%5Bfirst_order%5D=0
&custom_data%5Bproducts_list%5D=First+product%2C+Second+product
&custom_data%5B_reporting_data_1%5D=my+custom+data+1
&custom_data%5B_reporting_data_2%5D=my+custom+data+2
&custom_data%5B_reporting_data_3%5D=my+custom+data+3
&custom_data%5B_reporting_data_4%5D=my+custom+data+4
&custom_data%5B_reporting_data_5%5D=my+custom+data+5
&custom_data%5Bshipping_method%5D=click+and+collect
&avs_result=
&cvc_result=
&eci=7
&payment_product=postfinance-card
&payment_method=
&fraud_screening%5Bscoring%5D=30
&fraud_screening%5Bresult%5D=accepted
&fraud_screening%5Breview%5D=
&order%5Bid%5D=HP1065
&order%5Bdate_created%5D=2019-08-29T15%3A24%3A27%2B0000
&order%5Battempts%5D=1
&order%5Bamount%5D=100.00
&order%5Bshipping%5D=10.00
&order%5Btax%5D=15.00
&order%5Bdecimals%5D=2
&order%5Bcurrency%5D=CHF
&order%5Bcustomer_id%5D=123456
&order%5Blanguage%5D=en_EN
&order%5Bemail%5D=jane.doe%40test.com
To consider an accepted payment, it is appropriate to rely on the server-to-server notification containing the following values:
status=118
message=Captured
You can receive the server-to-server notification in:
- POST "application/x-www-form-urlencoded" format
- POST XML
POST accepted payment confirmation server-to-server notification example:
state=completed
&test=true
&mid=00001234567
&attempt_id=1
&authorization_code=TEST
&transaction_reference=800004137998
&date_created=2019-08-29T15%3A24%3A27%2B0000
&date_updated=2019-08-29T15%3A24%3A37%2B0000
&date_authorized=2019-08-29T15%3A24%3A36%2B0000
&status=118
&message=Captured
&authorized_amount=100.00
&captured_amount=100.00
&refunded_amount=0.00
&decimals=2
¤cy=CHF
&ip_address=0.0.0.0
&ip_country=
&device_id=
&custom_data%5Bfirst_order%5D=0
&custom_data%5Bproducts_list%5D=First+product%2C+Second+product
&custom_data%5B_reporting_data_1%5D=my+custom+data+1
&custom_data%5B_reporting_data_2%5D=my+custom+data+2
&custom_data%5B_reporting_data_3%5D=my+custom+data+3
&custom_data%5B_reporting_data_4%5D=my+custom+data+4
&custom_data%5B_reporting_data_5%5D=my+custom+data+5
&custom_data%5Bshipping_method%5D=click+and+collect
&avs_result=
&cvc_result=
&eci=7
&payment_product=postfinance-card
&payment_method=
&fraud_screening%5Bscoring%5D=0
&fraud_screening%5Bresult%5D=accepted
&fraud_screening%5Breview%5D=
&order%5Bid%5D=HP1065
&order%5Bdate_created%5D=2019-08-29T15%3A24%3A27%2B0000
&order%5Battempts%5D=1
&order%5Bamount%5D=100.00
&order%5Bshipping%5D=10.00
&order%5Btax%5D=15.00
&order%5Bdecimals%5D=2
&order%5Bcurrency%5D=CHF
&order%5Bcustomer_id%5D=123456
&order%5Blanguage%5D=en_EN
&order%5Bemail%5D=jane.doe%40test.com
Comentários
0 comentário
Artigo fechado para comentários.