Hosted payment page
Redirect your customers to a secure Paytrim payment page, so card data never reaches your systems.
With the hosted payment page, Paytrim shows the payment form and handles every redirect the payment needs, including 3-D Secure. Your customers enter their payment details on the hosted page, so you never store or process card data. This keeps your PCI DSS scope as small as possible.
How it works
Create an order
Your server creates an order with the amount, currency and return_url.
Redirect your customer
You redirect your customer to the order_url in the response. The page shows every payment method that's active in your project.
Your customer pays and returns
Your customer selects a payment method and completes the payment. Afterwards, they're redirected to your return_url.
Confirm the result
You receive a webhook and retrieve the order to check its status.
Create an order
Send the order details and the customer details to the API:
curl https://api.pay.paytrim.com/v1/orders/ \
--user "$API_KEY:" \
--header "Content-Type: application/json" \
--data '{
"currency": "EUR",
"amount": 995,
"merchant_order_id": "EXAMPLE001",
"description": "Example order",
"return_url": "https://www.example.com/order/EXAMPLE001",
"webhook_url": "https://www.example.com/webhook",
"customer": {
"merchant_customer_id": "123456789",
"email_address": "user@example.com",
"first_name": "John",
"last_name": "Smith",
"address_type": "billing",
"address": "100 Main Street",
"postal_code": "SW1A 1AA",
"city": "London",
"country": "GB",
"locale": "en-GB",
"phone_numbers": ["+441234566788"],
"ip_address": "192.0.2.1"
}
}'The response contains the new order. The response is shortened:
{
"id": "9aeef5a5-d717-4c5f-a227-89183b9f34c5",
"amount": 995,
"currency": "EUR",
"merchant_order_id": "EXAMPLE001",
"description": "Example order",
"expiration_period": "PT1H",
"flags": ["is-test"],
"order_url": "https://api.pay.paytrim.com/pay/9aeef5a5-d717-4c5f-a227-89183b9f34c5/select-payment-method/",
"return_url": "https://www.example.com/order/EXAMPLE001",
"status": "new"
}Redirect your customer to the order_url. When the payment is done, your customer goes to your return_url.
Don't rely on the redirect alone
Your customer can close the browser before they're redirected, and anyone can open your return_url. Always retrieve the order from your server before you show a confirmation or deliver.
Show only some payment methods
By default, the hosted payment page shows every payment method that's active in your project. To show a subset, add a payment_methods list to the order. For example, only Apple Pay and Google Pay:
{
"currency": "EUR",
"amount": 995,
"merchant_order_id": "EXAMPLE001",
"description": "Example order",
"return_url": "https://www.example.com/order/EXAMPLE001",
"payment_methods": ["apple-pay", "google-pay"]
}See payment methods for the identifiers.
Let your customer choose in your own checkout
You can also show the payment methods in your own checkout and send your customer straight to the selected method. This skips the method selection on the hosted page, while the hosted page still collects the payment details.
Add a transactions list with the selected payment_method. For cards:
curl https://api.pay.paytrim.com/v1/orders/ \
--user "$API_KEY:" \
--header "Content-Type: application/json" \
--data '{
"currency": "EUR",
"amount": 995,
"merchant_order_id": "EXAMPLE001",
"description": "Example card order",
"return_url": "https://www.example.com/order/EXAMPLE001",
"webhook_url": "https://www.example.com/webhook",
"transactions": [
{
"payment_method": "credit-card"
}
],
"customer": {
"merchant_customer_id": "123456789",
"email_address": "user@example.com",
"first_name": "John",
"last_name": "Smith",
"address_type": "billing",
"address": "100 Main Street",
"postal_code": "SW1A 1AA",
"city": "London",
"country": "GB",
"ip_address": "192.0.2.1"
}
}'The response contains the order with a transaction. The response is shortened:
{
"id": "23cd147d-cd2b-4df6-ae50-199de346ded1",
"amount": 995,
"currency": "EUR",
"status": "new",
"transactions": [
{
"id": "12774973-2ff1-49f5-926c-b5dc471ee96b",
"amount": 995,
"currency": "EUR",
"expiration_period": "PT30M",
"is_capturable": false,
"payment_method": "credit-card",
"payment_url": "https://api.pay.paytrim.com/pay/23cd147d-cd2b-4df6-ae50-199de346ded1/select-payment-method/credit-card/12774973-2ff1-49f5-926c-b5dc471ee96b/",
"status": "new"
}
]
}Redirect your customer to the payment_url of the transaction, not to the order_url.
Fields
Order fields
| Field | Required | Description |
|---|---|---|
currency | Yes | ISO 4217 currency code, such as EUR, GBP or USD. |
amount | Yes | Amount in the smallest currency unit: 1234 is € 12.34. |
merchant_order_id | Recommended | Your own order reference. |
description | Recommended | Description of the order. |
return_url | Recommended | Where your customer goes after the payment. Without it, your customer stays on the Paytrim result page. |
failure_url | No | Where your customer goes when the payment fails: the status is cancelled, expired or error. |
webhook_url | No | Where status changes are sent. Overrides the webhook URL of the project for this order. |
payment_methods | No | List of payment method identifiers to show on the hosted payment page. |
expiration_period | No | How long the payment page stays valid, as an ISO 8601 duration such as PT1H for one hour. |
transactions | No | One transaction with the payment_method your customer selected in your checkout. |
Customer fields
Send the customer details in the customer object. Card schemes use them for 3-D Secure risk assessment, so complete details lead to more frictionless payments. Your acquirer can require some of them.
| Field | Description |
|---|---|
merchant_customer_id | Your own customer reference. |
email_address | Customer's email address. |
first_name | Customer's first name. 1 to 120 characters: letters, digits, spaces and , . -. |
last_name | Customer's last name. Same format as first_name. |
address_type | Type of the address. Use billing. |
address | Street and house number of the billing address. 1 to 120 characters: letters, digits, spaces and , . -. |
postal_code | Postal code. 1 to 10 characters, uppercase letters and digits with at most one space, such as SW1A 1AA. |
city | City. 1 to 120 characters: letters, digits, spaces and , . -. |
country | Country as an ISO 3166-1 alpha-2 code, such as GB or NL. |
phone_numbers | List of phone numbers, including the country code. |
ip_address | IP address of your customer's device. |
locale | Language of the hosted payment page. |
Languages
The hosted payment page is available in these languages. Set the locale of the customer to one of these values:
en-GB, de-DE, nl-NL, nl-BE, fr-BE, fr-FR, sv-SE, no-NO, da-DK, it-IT, pl-PL, es-ES
E-wallet merchants
If you're an e-wallet merchant, also identify the account of your customer that the payment funds. Add these fields to the payment_method_details of the transaction:
| Field | Description |
|---|---|
receiver_account_number | Your customer's account number with you. 1 to 50 printable ASCII characters. |
receiver_account_number_type | Type of the account number: email, phone-number, wallet-id or social-network-id. |
"transactions": [
{
"payment_method": "credit-card",
"payment_method_details": {
"receiver_account_number": "123456",
"receiver_account_number_type": "wallet-id"
}
}
]Next steps
- Handle webhooks to hear about status changes.
- Check the order status before you deliver.
- Test your integration with test cards and amounts.