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

General Errors

Parameters

Request Header Parameters

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.
  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 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.
  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.
- 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_logo
- URL for the image of the client's logo.
  To configure this field, 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.
- 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.
- page_expiration
- End of the time when the customer can use the payment link, in 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 -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://www.rapyd.com",
        "complete_payment_url": "https://www.rapyd.com"
    },
    "max_payments":"3"
}
'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "60d647c7-f7e5-4849-864c-92f94a072591"
    },
    "data": {
        "id": "hp_reuse_1921d09bf0fe23922887fb4282be51dc",
        "amount": 100,
        "currency": "GBP",
        "country": "GB",
        "amount_is_editable": false,
        "merchant_reference_id": "payment link",
        "template": {
            "error_payment_url": "https://www.rapyd.com",
            "complete_payment_url": "https://www.rapyd.com"
        },
        "customer": "",
        "requested_currency": null,
        "fixed_side": null,
        "max_payments": 3,
        "status": "NEW",
        "language": "en",
        "org_id": "b73f63ba-ee20-4070-a994-2c0d5f0c2f7c",
        "merchant_color": "",
        "merchant_logo": "",
        "merchant_website": "https://www.rapyd.net",
        "merchant_customer_support": {},
        "merchant_alias": "Doc Team",
        "merchant_terms": "",
        "merchant_privacy_policy": "",
        "page_expiration": 1716201269,
        "redirect_url": "https://qa.rapyd.ly/pay/STVh06Pg"
    }
}

Editable amount

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.com",
        "complete_payment_url": "https://www.rapyd.com"
    }
}
'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "4411af1c-f390-4d8d-baf0-e98e35c2bfad"
    },
    "data": {
        "id": "hp_reuse_8eb6eddd298498fd0cfb145aca2efb70",
        "amount": 100,
        "currency": "GBP",
        "country": "GB",
        "amount_is_editable": true,
        "merchant_reference_id": "payment link",
        "redirect_url": "https://sbox.rapyd.ly/pay/9j3n8vrO",
        "template": {
            "error_payment_url": "https://www.rapyd.com",
            "complete_payment_url": "https://www.rapyd.com"
        },
        "customer": "",
        "status": "NEW",
        "language": "en",
        "merchant_color": "09a677",
        "merchant_logo": "https://iconslib.rapyd.net/merchant-logos/ohpc_8df12e51102d26bdc7e2321209878.jpg",
        "merchant_website": "https://www.rapyd.net",
        "merchant_customer_support": {
            "url": "https://www.rapyd.net",
            "email": "johndoe@rapyd.net",
            "phone_number": "55555555555"
        },
        "max_payments": null,
        "merchant_alias": "rapyd",
        "merchant_terms": "https://www.termsfeed.com/terms-conditions-generator/",
        "merchant_privacy_policy": "https://www.privacypolicies.com/blog/privacy-policy-template/",
        "page_expiration": 1699952336
    }
}

Open amount

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.com",
        "complete_payment_url": "https://www.rapyd.com"
    }
}
'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "346a0171-ead9-48db-8765-d79c404cda56"
    },
    "data": {
        "id": "hp_reuse_8736c82276017fabf3953f34ae31e26a",
        "amount": null,
        "currency": "GBP",
        "country": "GB",
        "amount_is_editable": true,
        "merchant_reference_id": "payment link",
        "redirect_url": "https://sbox.rapyd.ly/pay/7VhtZQ2y",
        "template": {
            "error_payment_url": "https://www.rapyd.com",
            "complete_payment_url": "https://www.rapyd.com"
        },
        "customer": "",
        "status": "NEW",
        "language": "en",
        "merchant_color": "09a677",
        "merchant_logo": "https://iconslib.rapyd.net/merchant-logos/ohpc_8df12e51102d26bdc7e2321209878.jpg",
        "merchant_website": "https://www.rapyd.com",
        "merchant_customer_support": {
            "url": "https://www.rapyd.com",
            "email": "johndoe@rapyd.net",
            "phone_number": "55555555555"
        },
        "max_payments": null,
        "merchant_alias": "rapyd",
        "merchant_terms": "https://www.termsfeed.com/terms-conditions-generator/",
        "merchant_privacy_policy": "https://www.privacypolicies.com/blog/privacy-policy-template/",
        "page_expiration": 1699952396
    }
}

Bad Request - Missing fields

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"
    }
}
'

{
    "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 -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"
    }
}
'

{
    "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"
    }
}

Unauthorized

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.com",
        "complete_payment_url": "https://www.rapyd.com"
    }
}
'

{
    "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

Create Payment Link

Note

Parameters

Request Header Parameters

Request Body Parameters

Response Parameters

Note

Search results