--- title: "Retrieve Checkout Page" source_url: https://docs.rapyd.net/en/retrieve-checkout-page.html lang: en --- # Retrieve Checkout Page Retrieve a checkout page. > **Note:** > > - The code samples include successful requests (200) and bad requests (400). > > - For error messages that appear due to bad requests (400), see: > > - [General Errors](https://docs.rapyd.net/en/general-errors.md "General Errors") > - [Checkout Errors](https://docs.rapyd.net/en/checkout-errors.md "Checkout Errors") > - For information about unauthorized request (401) and other authentication errors, see [Troubleshooting Authentication and Authorization Errors](https://docs.rapyd.net/en/troubleshooting-authentication-and-authorization-errors.md "Troubleshooting Authentication and Authorization Errors"). ### Parameters ### Request Path Parameters - - checkout - ID of the checkout page. String starting with **checkout_**. ### Request Header Parameters - - access_key - Unique access key provided by Rapyd for each authorized user. See [Developers](https://docs.rapyd.net/en/developers.md "Developers"). - - Content-Type - Indicates that the data appears in JSON format. Set to **application/json**. - - salt - Random string. Recommended length: 8-16 characters. - - signature - Signature calculated for each request individually. See [Request Signatures](https://docs.rapyd.net/en/request-signatures.md "Request Signatures"). - - timestamp - Timestamp for the request, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time") (seconds). ### 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. - - purpose_code - Describes the purpose of the AFT transaction. - - 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](https://docs.rapyd.net/en/capture-payment.md "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](https://docs.rapyd.net/en/list-countries.md "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](https://docs.rapyd.net/en/create-checkout-page.md "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](https://docs.rapyd.net/en/create-checkout-page.md "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](https://docs.rapyd.net/en/create-checkout-page.md "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](https://docs.rapyd.net/en/create-checkout-page.md "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](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "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](https://docs.rapyd.net/en/list-supported-languages.md "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. - - max_payment_retries_attempt - Indicates the number of times Rapyd can attempt to create a payment after an initial failure. - - 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](https://docs.rapyd.net/en/customizing-your-hosted-page.md "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](https://docs.rapyd.net/en/customizing-your-hosted-page.md "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_ewallet - ID of the Rapyd wallet that serves as the merchant's wallet. String starting with **ewallet_**. Restricted to Payment Facilitators (PayFac). See also the 'Create Checkout page with merchant wallet' sample on this page. - - 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](https://docs.rapyd.net/en/get-payment-method-required-fields.md "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](https://docs.rapyd.net/en/customizing-your-hosted-page.md "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](https://docs.rapyd.net/en/customizing-your-hosted-page.md "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](https://docs.rapyd.net/en/customizing-your-hosted-page.md "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](https://docs.rapyd.net/en/customizing-your-hosted-page.md "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](https://docs.rapyd.net/en/customizing-your-hosted-page.md "Customizing Your Hosted Page"). - - metadata - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata"). - - page_expiration - End of the time when the customer can use the hosted page, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "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](https://docs.rapyd.net/en/create-payment.md "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](https://docs.rapyd.net/en/create-payment.md "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](https://docs.rapyd.net/en/get-payment-method-required-fields.md "Get Payment Method Required Fields"). - - metadata - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "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](https://docs.rapyd.net/en/list-payment-methods-by-country.md "List Payment Methods by Country"). See [Configuring List of Payment Methods](https://docs.rapyd.net/en/configuring-list-of-payment-methods.md "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](https://docs.rapyd.net/en/configuring-list-of-payment-methods.md "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](https://docs.rapyd.net/en/configuring-list-of-payment-methods.md "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](https://docs.rapyd.net/en/configuring-list-of-payment-methods.md "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](https://docs.rapyd.net/en/saving-a-european-card-while-creating-a-payment.md "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](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - /v1/checkout/:checkout - Retrieve Checkout Page - ```curl 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' ``` - ```json { "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 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' ``` - ```json { "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" } } ```