--- title: "Create Payment Link" source_url: https://docs.rapyd.net/en/create-payment-link.html lang: en --- # Create Payment Link Creates a reusable link for a hosted payment page. A customer can use the link and the hosted payment page multiple times. After providing required information, the customer is redirected seamlessly to a Rapyd Checkout page to complete the payment. You can create the link for everyone or for a specific customer. You can make the payment amount fixed, editable, or open. > **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"). > - 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 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**. - - idempotency - A unique key that prevents the platform from creating the same object twice. See [Idempotency](https://docs.rapyd.net/en/idempotency.md "Idempotency"). - - 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). ### Request Body Parameters - - 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. On the hosted payment page, the customer: - Cannot modify the amount when `amount_is_editable` is **false** or not used. - Can modify the amount when `amount_is_editable` is **true** and `amount` has a positive value. - Must enter an amount when `amount_is_editable` is **true** and `amount` is **0**, **null**, or not used. - - amount_is_editable - Determines whether the customer can edit the amount. - **true** - The customer can edit the amount. - **false** - The customer cannot edit the amount. false - - checkout - Optional parameters for the checkout page. - - country - The two-letter ISO 3166-1 ALPHA-2 code for the country. - - currency - In transactions without FX, defines the currency of the transaction. Three-letter ISO 4217 code. In FX transactions: - When `fixed_side` is **buy**, it is the currency received in the Rapyd wallet. - When `fixed_side` is **sell**, it is the currency charged to the buyer. See also `fixed_side` and `requested_currency` fields. - - customer - ID of a specific customer. String starting with **cus_**. Restricts the payment link to the customer. - - fixed_side - Indicates whether the FX rate is fixed for the buy side (seller) or for the sell side (buyer). - **buy** - The currency that the Rapyd Wallet receives for goods or services. Fixed side buy relates to the seller (merchant) funds. 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 currency that the buyer is charged for purchasing goods or services. Fixed side sell relates to the buyer (customer) funds. 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. buy See also `requested_currency`. - - 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. - - merchant_ewallet - ID of the Rapyd wallet that serves as the merchant's wallet. String starting with **ewallet_.** Restricted to Payment Facilitator (PayFac). See also the 'Create Payment Link with merchant wallet' sample on this page. Contact Rapyd Client Support before using this field. - - max_payments - Indicates the maximum number of times that the payment link can be used for payments. When not indicated, there is no limit. - - merchant_reference_id - Identifier defined by the client for reference purposes. Limit: 45 characters. - requested_currency - Currency for one side of an FX transaction. Three-letter ISO 4217 code. - When `fixed_side` is **sell**, it is the currency received in the Rapyd Wallet. - When `fixed_side` is **buy**, it is the currency charged to the buyer (customer). Relevant to payments with FX. See also `currency` and `fixed_side` fields. ### Response Parameters - - 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. On the hosted payment page, the customer: - Cannot modify the amount when `amount_is_editable` is **false** or not used. - Can modify the amount when `amount_is_editable` is **true** and `amount` has a positive value. - Must enter an amount when `amount_is_editable` is **true** and `amount` is **0**, **null**, or not used. - - amount_is_editable - Determines whether the customer can edit the amount. - **true** - The customer can edit the amount. - **false** - The customer cannot edit the amount. - - country - The two-letter ISO 3166-1 ALPHA-2 code for the country. - - currency - - **Transactions without FX** - Indicates the currency of the amount received by the recipient. - **FX transactions** - Indicates the currency of the amount paid by the buyer. - - customer - ID of a specific customer. String starting with **cus_**. Restricts the payment link to the customer. - - fixed_side - Indicates whether the FX rate is fixed for the buy side (seller) or for the sell side (buyer). - **buy** - The currency that the Rapyd Wallet receives for goods or services. Fixed side buy relates to the seller (merchant) funds. 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 currency that the buyer is charged for purchasing goods or services. Fixed side sell relates to the buyer (customer) funds. 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 payment link. String starting with **hp_reuse_**. - - 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_payments - Indicates the maximum number of times that the payment link can be used for payments. When not defined, there is no limit. - - 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_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_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. - - merchant_wallet - ID of the Rapyd wallet that serves as the merchant's wallet. String starting with **ewallet_**. Restricted to Payment Facilitator (PayFac). See also the 'Create Payment Link with merchant wallet' sample on this 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"). - - page_expiration - End of the time when the customer can use the payment link, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). One year after creation. > **Note:** > > Each hosted page that the payment link generates expires 14 days after creation. - - requested_currency - Currency for one side of an FX transaction. Three-letter ISO 4217 code. - When `fixed_side` is **sell**, it is the currency received in the Rapyd Wallet. - When `fixed_side` is **buy**, it is the currency charged to the buyer (customer). - - redirect_url - The payment link URL. - - status - Status of the hosted payment page. One of the following: - **NEW** - The hosted page was created. - **EXP** - The hosted page expired. - - template - Optional parameters for the checkout page. - /v1/hosted/collect/payments - Fixed amount with maximum payments defined - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/hosted/collect/payments' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "country": "GB", "currency": "GBP", "amount": "100", "merchant_reference_id": "payment link", "language": "EN", "checkout": { "error_payment_url": "https://error.rapyd.com", "complete_payment_url": "https://complete.rapyd.com" }, "max_payments": 3 }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "66afd8dd-53a0-456f-a201-cc8e6694fe1e" }, "data": { "id": "hp_reuse_9ac0e8912b058a4d9169590ec64c2cd4", "amount": 100, "currency": "GBP", "country": "GB", "amount_is_editable": false, "merchant_reference_id": "payment link", "template": { "error_payment_url": "https://error.rapyd.com", "complete_payment_url": "https://complete.rapyd.com" }, "customer": "", "requested_currency": null, "fixed_side": null, "max_payments": 3, "status": "NEW", "language": "en", "org_id": "153e08b8-4bf3-4cb9-bb03-79d405eaed2a", "merchant_color": "323fff", "merchant_logo": "", "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": 1795434475, "redirect_url": "https://sbox.rapyd.ly/pay/rlna3Xdb" } } ``` - Editable amount - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/hosted/collect/payments' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "country": "GB", "currency": "GBP", "amount": "100", "amount_is_editable": true, "merchant_reference_id": "payment link", "language": "EN", "checkout": { "error_payment_url": "https://www.rapyd.net", "complete_payment_url": "https://www.rapyd.net/developers/" } }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "0c2e4a5b-1f95-4a7b-af56-12cde67a3c75" }, "data": { "id": "hp_reuse_a964d7c0592ca1b6fb54f211fff204c0", "amount": 100, "currency": "GBP", "country": "GB", "amount_is_editable": true, "merchant_reference_id": "payment link", "template": { "error_payment_url": "https://www.rapyd.net", "complete_payment_url": "https://www.rapyd.net/developers/" }, "customer": "", "requested_currency": null, "fixed_side": null, "max_payments": null, "status": "NEW", "language": "en", "org_id": "153e08b8-4bf3-4cb9-bb03-79d405eaed2a", "merchant_color": "323fff", "merchant_logo": "", "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": 1795434677, "redirect_url": "https://sbox.rapyd.ly/pay/CUDkdBcV" } } ``` - Open amount - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/hosted/collect/payments' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "country": "GB", "currency": "GBP", "amount_is_editable": true, "merchant_reference_id": "payment link", "language": "EN", "checkout": { "error_payment_url": "https://www.rapyd.net", "complete_payment_url": "https://www.rapyd.net/developers/" } }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "b98acc9a-3d0d-489e-9e10-7a5643a09d86" }, "data": { "id": "hp_reuse_1ea5d28c63af892b9def5dff3177e342", "amount": null, "currency": "GBP", "country": "GB", "amount_is_editable": true, "merchant_reference_id": "payment link", "template": { "error_payment_url": "https://error.rapyd.net", "complete_payment_url": "https://complete.rapyd.net" }, "customer": "", "requested_currency": null, "fixed_side": null, "max_payments": null, "status": "NEW", "language": "en", "org_id": "153e08b8-4bf3-4cb9-bb03-79d405eaed2a", "merchant_color": "323fff", "merchant_logo": "", "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": 1795434738, "redirect_url": "https://sbox.rapyd.ly/pay/lScEj2mv" } } ``` - Create Payment Link with merchant wallet - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/hosted/collect/payments' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw ' { "amount": 100, "country": "us", "currency": "usd", "amount_is_editable": false, "merchant_reference_id": "reusable_id_merchant_xxxx", "customer_": "cus_3b0d0ab8589f0cdbb116b6b3c643d412", "checkout": { "error_payment_url": "http://exae.com/error", "complete_payment_url": "http://example.com/complete", "language": "en", "page_expiration": 1654853231, "merchant_ewallet" : "ewallet_8a5077a7d3b4778c73393b7171566ced" } }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "8b963ec1-71dd-4175-922e-226e6fcd21b6" }, "data": { "id": "hp_reuse_24821c11b66ee7483ad758fffb9237b3", "amount": 100, "currency": "USD", "country": "US", "amount_is_editable": false, "merchant_reference_id": "reusable_id_merchant_xxxx", "template": { "merchant_ewallet": "ewallet_8a5077a7d3b4778c73393b7171566ced", "error_payment_url": "http://exae.com/error", "complete_payment_url": "http://example.com/complete" }, "customer": "", "requested_currency": null, "fixed_side": null, "max_payments": null, "status": "NEW", "language": "", "org_id": "65531d28-8f5f-4b77-b425-6597354026a5", "merchant_color": "", "merchant_logo": "", "merchant_website": "https://www.rapyd.net/", "merchant_customer_support": {}, "merchant_alias": "aft business", "merchant_terms": "", "merchant_privacy_policy": "", "page_expiration": 1781606450, "redirect_url": "https://qa.rapyd.ly/pay/FvgWwWu0" } } ``` - Bad Request - Missing fields - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/hosted/collect/payments' -H 'access_key: your-access-key-here' -H 'Content-Type: application/json' -H 'idempotency: your-idempotency-parameter-here' -H 'salt: your-random-string-here' -H 'signature: your-calculated-signature-here' -H 'timestamp: your-unix-timestamp-here' --data-raw ' { "currency": "GBP", "amount": "100", "amount_is_editable": true, "merchant_reference_id": "payment link", "language": "EN", "checkout": { "error_payment_url": "https://www.example678.com/error", "complete_payment_url": "https://www.example678.com/complete" } } ' ``` - ```json { "status": { "error_code": "MISSING_FIELDS - [COUNTRY]", "status": "ERROR", "message": "The request attempted an operation, but one or more required fields were missing. The request was rejected. Corrective action: Provide all of the fields that are listed at the end of the response code.", "response_code": "MISSING_FIELDS - [COUNTRY]", "operation_id": "3946e5b0-9207-4ba3-990a-eeee7cf3d901" } } ``` - Bad Request - Invalid field value - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/hosted/collect/payments' -H 'access_key: your-access-key-here' -H 'Content-Type: application/json' -H 'idempotency: your-idempotency-parameter-here' -H 'salt: your-random-string-here' -H 'signature: your-calculated-signature-here' -H 'timestamp: your-unix-timestamp-here' --data-raw ' { "country": "US", "currency": "USD", "amount": "100$", "amount_is_editable": true, "merchant_reference_id": "payment link", "language": "EN", "checkout": { "error_payment_url": "https://www.example678.com/error", "complete_payment_url": "https://www.example678.com/complete" } } ' ``` - ```json { "status": { "error_code": "INVALID_FIELDS - [AMOUNT]", "status": "ERROR", "message": "The request attempted an operation, but one or more of the fields did not have a valid value. The request was rejected. Corrective action: Use valid values. The names of the affected fields appear at the end of the error code. See the API Reference for details.", "response_code": "INVALID_FIELDS - [AMOUNT]", "operation_id": "3ee5715d-0071-4166-8cab-04c9fb727a26" } } ```