Customize the payment page

These options all go into the order you create in Accept a payment. See Create an order in the API reference for all fields.

Show only some payment methodsCopy Anchor Link

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 checkoutCopy Anchor Link

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.griner.io/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"
      }
    ]
  }'

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.griner.io/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.

To show Apple Pay or Google Pay in your own checkout without a redirect, see Your own checkout.

Apple Pay and Google PayCopy Anchor Link

On the hosted payment page, you don't need to register with Apple or Google. Once Apple Pay or Google Pay is active in your project, the hosted payment page shows its button along with your other payment methods. It only shows the Apple Pay button when your customer's device and browser support Apple Pay.

To send your customer straight to a wallet, set the payment_method of the transaction to apple-pay or google-pay, as in Let your customer choose in your own checkout.

To accept Google Pay, you must follow the Google Pay APIs Acceptable Use Policy and accept the Google Pay API Terms of Service.

To show the wallet buttons in your own checkout instead, see Apple Pay and Google Pay in your own checkout.

Prefill customer detailsCopy Anchor Link

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.

{
  "currency": "EUR",
  "amount": 995,
  "merchant_order_id": "EXAMPLE001",
  "description": "Example order",
  "return_url": "https://www.example.com/order/EXAMPLE001",
  "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"
  }
}

Set the languageCopy Anchor Link

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, fi-FI

Send failed payments to another pageCopy Anchor Link

After the payment, your customer goes to your return_url, whatever the result. To send your customer to another page when the payment fails, with order status cancelled, expired or error, add a failure_url to the order.

You still check the order status from your server: anyone can open either URL.

Change how long the page stays validCopy Anchor Link

Set the expiration_period of the order, as an ISO 8601 duration such as PT1H for one hour. When it ends before your customer pays, the order status becomes expired.

E-wallet merchantsCopy Anchor Link

If you're an e-wallet merchant, also identify the account of your customer that the payment funds. Add your customer's account number with you to the payment_method_details of the transaction as receiver_account_number, and its type as receiver_account_number_type: 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"
    }
  }
]