Retrieve Checkout Page

Retrieve a checkout page.

Note

Parameters

Request Path Parameters

- checkout
- ID of the checkout page. String starting with checkout_.

Request Header Parameters

Response Parameters

- account_funding_transaction
- Details of an account funding transaction (AFT), which transfers funds from a card to a cardholder's wallet. Contains the following fields:
  ewallet
  ID of a Rapyd wallet.
  payment_method_types
  Array of strings. One or more card payment method types that support AFT.
- amount
- The amount of the payment, in units of the currency defined in currency. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015. If the amount is a whole number, use an integer and not a decimal.
- cancel_checkout_url
- URL where the customer is redirected after pressing Back to Website to exit the hosted page. This URL overrides the merchant_website URL. Does not support localhost URLs.
- capture
- Determines when the payment is processed for capture. Relevant to card payments.
  true - Capture the payment immediately.
  false - Authorize the payment, then capture some or all of the payment at a later time, when the merchant runs the Capture Payment method.
- cart_items
- Describes the cart items that the customer is purchasing. These items are displayed at the checkout page. Contains the following fields:
  amount
  The price of the item in the currency defined in currency.
  amount_off
  The size of the discount, measured in the amount of money. Decimal. Range: Positive decimal number, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015.
  discount
  The total amount of money deducted from the payment for the discount. Decimal. Range: Positive decimal number, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015.
  image
  The image that appears in the checkout page for this item.
  name
  The name of the item.
  percent_off
  The size of the discount, measured in percent. Integer. Range: 1-100.
  quantity
  The quantity of the item.
- complete_checkout_url
- URL where the customer is redirected after pressing Finish to exit the hosted page. This URL overrides the merchant_website URL. Does not support localhost URLs.
- complete_payment_url
- URL where the customer is redirected when payment is successful, after returning from an external page such as a 3DS page. Does not support localhost URLs.
- country
- The two-letter ISO 3166-1 ALPHA-2 code for the country.
  To determine the code for a country, see List Countries.
- currency
- Defines the currency for the amount received by the seller (merchant). Three-letter ISO 4217 code.
  In FX transactions, when fixed_side is buy, it is the currency received by the merchant. When fixed_side is sell, it is the currency charged to the buyer.
- custom_elements
- Describes customizations of the page as it appears to the customer.
  billing_address_collect
  Determines whether the customer is asked to fill in the billing address. Relevant when a card payment method is selected.
  true - The address fields appear on the checkout page.
  false - The address fields appear only if the country is US, GB or CA.
  false
  Note
  When the customer already has address details, it is always displayed.
  cardholder_name
  The name of the card owner, printed on the front of the card.
  display_description
  Determines whether the checkout page displays the payment description.
  true - The payment description appears.
  false - The payment description does not appear.
  false
  Relevant when description is passed in the Create Checkout Page request.
  dynamic_currency_conversion
  Determines whether the checkout page displays multiple currency options for a payment.
  true - Multiple currency options appear.
  false - Currency options do not appear.
  false
  When the customer selects the requested currency, the checkout page displays the following information:
  The original amount and currency.
  The converted amount in the requested currency.
  The exchange rate.
  Relevant when:
  The Create Checkout Page request passes requested_currency.
  fixed_side is buy.
  One or more payment methods support the values for currency and requested_currency.
  merchant_color
  Reserved.
  merchant_currency_only
  In a payment with FX where fixed_side=buy, determines whether the buyer's currency and the exchange rate appear. One of the following:
  true - The currency and the exchange rate are hidden.
  false - The currency and the exchange rate appear.
  false
  payment_fees_display
  Determines whether payment fees appear on the checkout page.
  true - Payment fees appear when the payment_fees object is set in the Create Checkout Page request.
  false - Payment fees do not appear.
  true
  required_customer_fields
  Indicates the list of fields that the customer has to fill in on the payment page before completing the payment via hosted checkout. Valid values include:
  name– The customer's full name (default).
  email – The customer's email address.
  phone_number – The customer's phone number.
  address – The address of the customer.
  save_card_default
  Determines whether the save card checkbox is checked by default.
  true - The save card checkbox is checked.
  false - The save card checkbox is cleared.
  false
  Relevant when customer_id is passed in the Create Checkout Page request.
- customer
- ID of the customer. String starting with cus_. When used, the customer has the option to save card details for future purchases. This field is for some payment methods and for all company-type wallets.
- description
- Description of the payment transaction. To display the description, set display_description to true in custom_elements.
- error_payment_url
- URL where the customer is redirected when payment is not successful, after returning from an external page, such as a 3DS page. Does not support localhost URLs.
- escrow
- Determines whether the payment is held in escrow for later release.
- escrow_release_days
- Determines the number of days after creation of the payment that funds are released from escrow. Funds are released at 5:00 pm GMT on the day indicated. Integer, range: 1-90.
- ewallet
- ID of the wallet that the money is paid into. String starting with ewallet_. Relevant for specifying a single wallet in the request.
- ewallets
- Specifies one or more wallets that the money is collected into.
  amount
  The amount of the payment to the wallet, in units of the currency defined in currency.
  ewallet_id
  ID of the wallet.
  percent
  The percentage that is paid to the wallet out of the total payment.
  refunded_amount
  The total amount refunded against this payment, in units of the currency defined in currency.
- expiration
- Time when the payment expires if it is not completed, in Unix time. When both expiration and payment_expiration are set, the payment expires at the earlier time.
  14 days after creation of the checkout page.
- fixed_side
- Indicates whether the FX rate is fixed for the buy side (seller) or for the sell side (buyer). One of the following values:
  - buy - The checkout page shows the currency that the seller (merchant) receives for goods or services. For example, a US-based merchant wants to charge 100 USD. The buyer (customer) pays the amount in MXN that converts to 100 USD.
  - sell - The checkout page shows the currency that the buyer is charged with to purchase goods or services from the seller. For example, a US-based merchant wants to charge a buyer 2,000 MXN and will accept whatever amount in USD that is converted from 2,000 MXN.
- id
- ID of the Rapyd checkout page. String starting with checkout_.
- language
- Determines the default language of the hosted page. For a list of values, see List Supported Languages.
  When this parameter is null, the language of the user's browser is used.
  If the language of the user's browser cannot be determined, the default language is English.
- merchant_alias
- Client's name.
  Rapyd
- merchant_color
- Color of the call-to-action (CTA) button on the hosted page.
  To configure this field, use the Client Portal. See Customizing Your Hosted Page.
- merchant_customer_support
- Contains details of the client’s customer support. To configure these fields, use the Client Portal. See Customizing Your Hosted Page.
  email
  Email address.
  url
  URL for the client's customer support service.
  phone_number
  Phone number for contacting the client's customer support service.
- merchant_fields
- Object that contains payment method fields that the merchant fills in. Can include one or both of the following:
  - payment_method_options object.
  - payment_options object.
  The fields of both objects are not displayed to the customer on the hosted page. To retrieve the fields of both objects for a payment method, use Get Payment Method Required Fields.
- merchant_logo
- URL for the image of the client's logo.
  To configure this field, use the Client Portal. See Customizing Your Hosted Page.
- merchant_main_button
- A string that represents the text on the main Call to Action (CTA) button. One of the following:
  - place_your_order - Place Your Order.
  - pay - Pay.
  - pay_now - Pay Now.
  - make_payment - Make Payment.
  - purchase - Purchase.
  - buy - Buy.
  - donate - Donate.
  place_your_order
  To configure this button, use the Client Portal. See Customizing Your Hosted Page.
- merchant_privacy_policy
- URL for the terms and conditions of the agreement between the client and the client’s customers.
  To configure this field, use the Client Portal. See Customizing Your Hosted Page.
- merchant_reference_id
- Identifier defined by the client for reference purposes. Limit: 45 characters.
- merchant_terms
- URL for the client's terms and conditions. To configure this field, use the Client Portal. See Customizing Your Hosted Page.
- merchant_website
- The URL where the customer is redirected after exiting the hosted page.
  Relevant when one or both of the following fields is unset:
  cancel_url
  complete_url
  To configure this field, use the Client Portal. See Customizing Your Hosted Page.
- metadata
- A JSON object defined by the client. See Metadata.
- page_expiration
- End of the time when the customer can use the hosted page, in Unix time. If page_expiration is not set, the hosted page expires 14 days after creation.
  Range: 1 minute to 30 days.
- payment
- Describes the payment that will result from the hosted page. The id and status values are null until the customer successfully submits the information on the hosted page. For more information about fields in the 'payment' object, see Create Payment.
- payment_expiration
- Length of time for the payment to be completed after it is created, measured in seconds. When both expiration and payment_expiration are set, the payment expires at the earlier time.
- payment_fees
- Defines transaction fees and foreign exchange fees. These are fees that the Rapyd merchant can define for its consumers in addition to the payment amount. They are not related to the fees Rapyd charges to its clients.
  transaction_fee
  Describes the fee for processing the transaction.
  calc_type
  Specifies how the fee is calculated. One of the following:
  net - The fee is deducted from the amount paid. For example, in a payment of $100 with a fee of 5%, the recipient receives $95.00 and the $5.00 fee goes to the client wallet.
  gross - The fee is added to the amount paid. For example, for a transaction of $100 with a fee of 5%, the sender pays $105.00.
  fee_type
  One of the following:
  percentage - A percentage of the transaction amount. For example, 5 percent is represented by value=5.
  absolute - A fixed amount.
  value
  The amount of the fee.
  fx_fee
  Describes the fees for processing the currency exchange. Relevant to payments with FX.
  calc_type
  Specifies how the fee is calculated. One of the following:
  net - The fee is deducted from the amount paid. For example, in a payment of $100 with a fee of 5%, the recipient receives $95.00 and the $5.00 fee goes to the client wallet.
  gross - The fee is added to the amount paid. For example, for a transaction of $100 with a fee of 5%, the sender pays $105.00.
  value
  The amount of the fee. Percentage.
  gross_fees
  The total gross fees for the transaction, in units defined by currency_code.
  net_fees
  The total net fees for the transaction, in units defined by merchant_requested_currency.
  total_merchant_fees
  The amount of the fee.
- payment_method
- Object that describes the payment method. This behavior is different from Create Payment. Contains the following fields:
  account_name_inquiry
  Data about the account name inquiry (ANI).
  account_name_inquiry_result
  Result of the account name inquiry. One of the following values:
  match - Indicates that the name provided in the request fully matched the issuing bank's records.
  partial match - Indicates that the name provided in the request partially matched the issuing bank's records.
  no match - Indicates that the name provided in the request did not match the issuing bank's records.
  not performed - Indicates that the account name inquiry was not performed.
  not supported - Indicates that the payment method does not support account name inquiries.
  account_name_inquiry_details
  Details of the account name inquiry (ANI).
  first_name
  Indicates the result of matching the cardholder's given name. One of the following values:
  match - Indicates that the first name provided in the request fully matched the first name in the issuing bank's records.
  partial match - Indicates that the first name provided in the request partially matched the first name in the issuing bank's records.
  no match - Indicates that first the name provided in the request did not match the first name in the issuing bank's records.
  middle_name
  Indicates the result of matching the cardholder's middle name. One of the following values:
  match - Indicates that the middle name provided in the request fully matched the middle name in the issuing bank's records.
  partial match - Indicates that the middle name provided in the request partially middle the first name in the issuing bank's records.
  no match - Indicates that the middle name provided in the request did not match the middle name in the issuing bank's records.
  last_name
  Indicates the result of matching the cardholder's family name. One of the following values:
  match - Indicates that the last name provided in the request fully matched the family name in the issuing bank's records.
  partial match - Indicates that the last name provided in the request partially matched the family name in the issuing bank's records.
  no match - Indicates that the last name provided in the request did not match the family name in the issuing bank's records.
  address
  Describes the address associated with the payment. Do not use an address ID.
  fields
  Contains the fields that are required for the payment method. See Get Payment Method Required Fields.
  metadata
  A JSON object defined by the client. See Metadata.
  name
  Name of the payment method.
  type
  The type of the payment method.
- payment_method_type
- The type of the payment method. For example, it_visa_card. To get a list of payment methods for a country, use List Payment Methods by Country. See Configuring List of Payment Methods.
- payment_method_type_categories
- A list of the categories of payment method that are supported on the checkout page. The categories appear on the page in the order provided. One or more of the following:
  - bank_redirect
  - bank_transfer
  - card
  - cash
  - ewallet
  See Configuring List of Payment Methods.
- payment_method_types_exclude
- List of payment methods that are excluded from display on the checkout page.
  See Configuring List of Payment Methods.
- payment_method_types_include
- List of payment methods that are displayed on the checkout page. The payment methods appear on the page in the order provided.
  See Configuring List of Payment Methods.
- recurrence_type
- Specifies the primary intended purpose of the saved payment method. See Saving a European Card While Creating a Payment. One of the following values:
  installment - Regular payments for a defined number of payment cycles.
  recurring - Regular payments for an indefinite period.
  unscheduled - Individual unrelated payments.
- redirect_url
- URL of the hosted page that is shown to the customer.
- requested_currency
- When fixed_side is sell, it is the currency received by the merchant.
  When fixed_side is buy, it is the currency charged to the buyer (customer). Three-letter ISO 4217 code.
  The checkout page displays the following information:
  - The original amount and currency.
  - The converted amount in the requested currency.
  - The exchange rate.
  Relevant to payments with FX.
- require_card_cvv
- Require the customer to enter their Card Verification Value (CVV) for each subsequent payment made using a saved card. Relevant to card payments.
  - true - Customer must enter CVV.
  - false - Customer not required to enter CVV.
- statement_descriptor
- A text description suitable for a customer's payment statement. 5-22 characters.
- status
- Status of the hosted page. One of the following:
  - NEW - The hosted page was created.
  - DON - Done. The payment was completed.
  - EXP - The hosted page expired.
  - INP - Creation of the payment is still in progress.
  - DEC - Rapyd Protect blocked the payment.
- timestamp
- Time of creation of the checkout page, in Unix time.

/v1/checkout/:checkout

Retrieve Checkout Page

curl -X get 'https://sandboxapi.rapyd.net/v1/checkout/checkout_4027d17e5cfad4a87677e18478a64cee' \
-H 'access_key: your-access-key-here' \
-H 'Content-Type: application/json' \
-H 'salt: your-random-string-here' \
-H 'signature: your-calculated-signature-here' \
-H 'timestamp: your-unix-timestamp-here'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "6f1a7b78-8bb1-4bf4-b265-a802ed0049c3"
    },
    "data": {
        "id": "checkout_4027d17e5cfad4a87677e18478a64cee",
        "status": "NEW",
        "language": "en",
        "org_id": "153e08b8-4bf3-4cb9-bb03-79d405eaed2a",
        "merchant_color": "323fff",
        "merchant_logo": null,
        "merchant_website": "https://example1234.net",
        "merchant_customer_support": {
            "url": "https://example1234.net",
            "email": "support@example1234.net",
            "phone_number": "121255551213"
        },
        "merchant_alias": "Doc Team",
        "merchant_terms": "https://example1234.net/terms_and_conditions",
        "merchant_privacy_policy": "https://example1234.net/privacy_policy",
        "page_expiration": 1764149335,
        "redirect_url": "https://sandboxcheckout.rapyd.net/?token=checkout_4027d17e5cfad4a87677e18478a64cee",
        "region": "EMEA",
        "geo_country": "IL",
        "merchant_main_button": "place_your_order",
        "recurrence_type": null,
        "cancel_checkout_url": "https://example1234.net",
        "complete_checkout_url": "https://example1234.net",
        "country": "SG",
        "currency": "SGD",
        "amount": 100.25,
        "payment": {
            "id": null,
            "amount": 100.25,
            "original_amount": 0,
            "is_partial": false,
            "currency_code": "SGD",
            "country_code": "SG",
            "status": null,
            "description": "Payment via Checkout",
            "merchant_reference_id": "2025-11-02a",
            "customer_token": "cus_4e25112ac20e144ad073a614dc46934b",
            "payment_method": null,
            "payment_method_data": {},
            "expiration": 0,
            "captured": false,
            "refunded": false,
            "refunded_amount": 0,
            "receipt_email": null,
            "redirect_url": null,
            "complete_payment_url": "http://complete.rapyd.net",
            "error_payment_url": "http://error.rapyd.net",
            "receipt_number": null,
            "flow_type": null,
            "address": null,
            "statement_descriptor": null,
            "transaction_id": null,
            "created_at": 0,
            "updated_at": 0,
            "metadata": null,
            "failure_code": null,
            "failure_message": null,
            "paid": false,
            "paid_at": 0,
            "dispute": null,
            "refunds": null,
            "order": null,
            "outcome": null,
            "visual_codes": {},
            "textual_codes": {},
            "instructions": {},
            "ewallet_id": null,
            "ewallets": [],
            "payment_method_options": {},
            "payment_method_type": null,
            "payment_method_type_category": null,
            "fx_rate": null,
            "merchant_requested_currency": null,
            "merchant_requested_amount": null,
            "fixed_side": null,
            "payment_fees": null,
            "invoice": null,
            "escrow": null,
            "group_payment": null,
            "cancel_reason": null,
            "initiation_type": null,
            "mid": null,
            "next_action": "not_applicable",
            "merchant_ewallet": null
        },
        "payment_method_type": null,
        "payment_method_type_categories": null,
        "payment_method_types_include": [
            "sg_grabpay_ewallet"
        ],
        "payment_method_types_exclude": null,
        "account_funding_transaction": null,
        "customer": "cus_4e25112ac20e144ad073a614dc46934b",
        "custom_elements": {
            "hide_save_card": false,
            "save_card_default": false,
            "display_description": false,
            "payment_fees_display": true,
            "merchant_currency_only": false,
            "billing_address_collect": false,
            "dynamic_currency_conversion": false
        },
        "timestamp": 1762939735,
        "payment_expiration": null,
        "cart_items": [],
        "escrow": null,
        "escrow_release_days": null,
        "require_card_cvv": false,
        "payment_method_types": [
            {
                "category": "ewallet",
                "order": 0,
                "types": [
                    {
                        "type": "sg_grabpay_ewallet",
                        "mapping": null,
                        "order": 0,
                        "image": "https://iconslib.rapyd.net/checkout/sg_grabpay_ewallet.png",
                        "instructions": [],
                        "name": "GrabPay eWallet",
                        "fields": [
                            {
                                "name": "number_type",
                                "type": "string",
                                "regex": "(fpan|tpan)",
                                "description": "Determining if number is funding PAN or token PAN",
                                "is_required": false
                            }
                        ],
                        "supported_currencies": [
                            "SGD"
                        ],
                        "payment_method_options": [
                            {
                                "name": "tavv",
                                "type": "String",
                                "regex": null,
                                "description": "Token Authentication Verification Value represented as a 20-byte value that is base64 encoded.",
                                "is_required": false,
                                "is_updatable": false
                            }
                        ],
                        "payment_options": [],
                        "supported_digital_wallet_providers": [],
                        "min_amount": null,
                        "max_amount": null,
                        "authorization_flow": false,
                        "is_conditional": false,
                        "supports_subscription": true,
                        "is_mobile_money": false,
                        "image_base64": null,
                        "is_crypto": false,
                        "is_redirect": false
                    }
                ]
            }
        ],
        "customer_payment_methods": []
    }
}

Bad Request - Hosted Page Not Found

curl -X get 'https://sandboxapi.rapyd.net/v1/checkout/checkout_408606a46b1e1e60507a2b2fc578143' \
-H 'access_key: your-access-key-here' \
-H 'Content-Type: application/json' \
-H 'salt: your-random-string-here' \
-H 'signature: your-calculated-signature-here' \
-H 'timestamp: your-unix-timestamp-here'

{
    "status": {
        "error_code": "ERROR_GET_HOSTED_PAGE_PAYMENT",
        "status": "ERROR",
        "message": "The request tried to retrieve a hosted page, but the page was not found. The request was rejected. Corrective action: Use the ID of a valid hosted page.",
        "response_code": "ERROR_GET_HOSTED_PAGE_PAYMENT",
        "operation_id": "a6111d09-de8a-4ca6-99e2-9fc185a95f89"
    }
}

Unauthorized

curl -X get 'https://sandboxapi.rapyd.net/v1/checkout/checkout_408606a46b1e1e60507a2b2fc578143' \
-H 'access_key: your-access-key-here' \
-H 'Content-Type: application/json' \
-H 'salt: your-random-string-here' \
-H 'signature: your-calculated-signature-here' \
-H 'timestamp: your-unix-timestamp-here'

{
    "status": {
        "error_code": "UNAUTHENTICATED_API_CALL",
        "status": "ERROR",
        "message": "The request was rejected due to an authentication issue. Corrective action: Check the status of your account in the 'Account Details' page of the Client Portal.",
        "response_code": "UNAUTHENTICATED_API_CALL",
        "operation_id": "034ff9bc-e27c-405b-8f8d-437becbc2358"
    }
}

In this section:

Documentation

Retrieve Checkout Page

Note

Parameters

Request Path Parameters

Request Header Parameters

Response Parameters

Note

Search results