Create Payment Link (API)

Overview

The Payment Link API allows merchants to create payment links and QR codes for their transactions dynamically. When you initiate a payment request, the API provides a payment URL and, if desired, a QR code image that can be shown to customers. Customers can complete their payment using the payment link or the QR code.

ℹ️
Note
This API is currently available only for Gateway Model. For availability in other countries, please contact your account executive.

Basic Flow (with customer prefil, save-card prompt)

Payment method — the customer sees the available card brands.
Select new card — opens the card entry flow.
Save card modal — the customer chooses whether to save the card for future payments (Cancel / No / Yes).
- If Yes → the card is saved for future use.
- If No → the card is used once and not saved.
Additional data — shown prefilled with the values sent in the customer object (email, name, document, address, etc.).
Enter card details — card number, expiration date, CVV, and cardholder name.
Confirm payment — the customer reviews the total amount and confirms.
Payment succeeded — the authorization code is displayed.

1. Choose the environment

You must invoke a POST request to the following URLs according to your needs:

Stage: https://h2h.stage.bamboopayment.com/api/v1/payments

Production: https://h2h.bamboopayment.com/api/v1/payments

2. Building the Request

Parameter	Type	Required?	Description
`amount`	`integer`	Yes	Payment amount in the smallest currency unit (e.g., 123450 represents 1,234.50)
`currencyCode`	`string`	Yes	Currency code in ISO 4217 alpha-3 format (e.g., `UYU`, `USD`)
`paymentType`	`string`	Yes	Type of payment. Must be "QR" to enable QR code generation or "CheckoutPro" only for Payment Link. When set to "QR", the `qrImageOptions` object becomes optional. For any other payment type, `qrImageOptions` must be null
`orderNumber`	`string`	No	Merchant's order identifier
`installments`	`integer[]`	No	List of installments. If not provided, takes default for each payment method configured in Merchant Portal. If not configured in Merchant Dashboard, takes `1`
`validForMinutes`	`integer`	No	Payment link validity time, after which it cannot be processed. Default: `15` minutes. Can only be reduced, not increased
`notificationUrl`	`string`	No	URL to notify the payment status. A default can be configured in Merchant Dashboard.
`metadataIn`	`object`	No	Additional data specific to each country and acquirer
`AllowUsePreregisteredCards`	`boolean`	No	Only applies when a `customer` object is provided. By default (field omitted), the checkout prompts the customer to save their card after entering it. Set explicitly to `false` to skip this prompt and go directly to the card entry screen — sending `true` is not a supported/valid use; the default behavior already covers that case.
`OnSuccessResultUrl`	`string`	No	Redirect URL the customer's browser is sent to when the payment result is Approved
`OnErrorResultUrl`	`string`	No	Redirect URL the customer's browser is sent to when the payment result is Rejected
`OnCancelResultUrl`	`string`	No	Redirect URL the customer's browser is sent to when the customer cancels the payment
`LineItems`	`array`	No	List of items/products to display on the checkout confirmation screen. See LineItems Object below

ℹ️
Note
OnSuccessResultUrl, OnErrorResultUrl, OnCancelResultUrl, and LineItems are not yet reflected elsewhere in this guide's examples. Confirm with your account executive whether these fields belong at the root of the request body or nested inside a sub-object, and whether LineItems amounts must sum to the top-level amount.

LineItems Object

Parameter	Type	Required?	Description
`title`	`string`	No	Short name of the product or service (e.g., "Seguro automotriz")
`Description`	`string`	No	Additional detail shown under the title (e.g., "Poliza 1566400")
`ImageUrl`	`string`	No	Image URL displayed next to the item on the checkout page
`UnitPrice`	`integer`	No	Item price, in the smallest currency unit (same convention as `amount`)

MetadataIn Object

Parameter	Type	Required?	Description
`metadataIn` → `invoiceNumber`	`string`	No	Invoice number associated with the sale
`metadataIn` → `isFinalConsumer`	`string`	No	Indicates if the sale is to a final consumer. Values: `true`, `false`
`metadataIn` → `taxableAmount`	`string`	No	VAT taxable amount

QRImageOptions Object

Parameter	Type	Required?	Description
`qrImageOptions` → `contentType`	`string`	No	Defines how the QR code content will be structured: `encodedJson`: Encodes payment data as Base64 JSON. This prevents QR scanners from automatically opening URLs. `url`: Embeds the RedirectUrl directly in the QR code for easy scanning and immediate redirection. Default: `encodedJson`
`qrImageOptions` → `encodedJsonPrefix`	`string`	No	Prepends the Base64 encoded payment information with this prefix. Useful for custom URL schemes in mobile apps.
`qrImageOptions` → `errorCorrectionLevel`	`string`	No	Sets the QR code's error correction capability: `low`: 7% error tolerance `medium`: 15% error tolerance `quartile`: 25% error tolerance `high`: 30% error tolerance Default: `quartile`
`qrImageOptions` → `imageFormat`	`string`	No	Specifies the pixel format of the image: `rgb24`: 8-bit RGB color (3 channels) `argb32`: 8-bit ARGB color with alpha channel (4 channels) Default: `rgb24`
`qrImageOptions` → `imagePixelFormat`	`string`	No	Specifies the image format: PNG, BMP, GIF, JPEG, PBM, TGA, TIFF, WEBP. Default: `png`
`qrImageOptions` → `scale`	`integer`	No	Width and height, in pixels, of each module of the QR code. Default: `10`
`qrImageOptions` → `border`	`integer`	No	Number of border modules added to each side of the QR code image. Default: `2`
`qrImageOptions` → `foregroundColor`	`string`	No	QR code color. Accepts color names or hex values. Default: "black"
`qrImageOptions` → `backgroundColor`	`string`	No	Background color. Accepts color names or hex values. Default: "white"
`qrImageOptions` → `borderColor`	`string`	No	Border color. Accepts color names or hex values. Default: Same as backgroundColor.
`qrImageOptions` → `embeddedImageName`	`string`	No	Name of a pre-loaded image in the Merchant Portal to display in the center of the QR code.
`qrImageOptions` → `embeddedImageRelativeWidth`	`float`	No	Size of the embedded image relative to the QR code width. Example: 0.25 means the image will occupy 25% of the QR code width. If not specified, the image retains its original size.

Important: This object is optional when paymentType is "QR" and must be null for any other payment type.

Customer Object

Parameter	Type	Required?	Description
`customer` → `identifier`	`string`	No	Unique identifier for the customer (e.g., email)
`customer` → `Email`	`string`	No	Customer's email address. Prefills the Email field on step 2 (Additional data)
`customer` → `firstName`	`string`	No	Customer's first name. Prefills First name
`customer` → `lastName`	`string`	No	Customer's last name. Prefills Last name
`customer` → `DocumentType`	`string`	No	Document type code, combining document + country (e.g., `"DNI.AR"`). Prefills Document type
`customer` → `DocumentNumber`	`string`	No	Customer's document number. Prefills Document number
`customer` → `phoneNumber`	`string`	No	Customer's phone number, including country code. Prefills Phone
`customer` → `Address`	`object`	No	Customer's address. See Address Object below
`customer` → `ExternalCustomerId`	`string`	No	Merchant's own internal customer identifier, used to reference this customer in future transactions

Address Object

Parameter	Type	Required?	Description
`customer` → `Address` → `detail`	`string`	No	Street address
`customer` → `Address` → `country`	`string`	No	ISO 3166-1 alpha-2 country code. For example: Argentina `AR`, Uruguay `UY`. Prefills Country
`customer` → `Address` → `state`	`string`	No	State/province. Prefills State
`customer` → `Address` → `city`	`string`	No	City. Prefills City
`customer` → `Address` → `postalCode`	`string`	No	Postal/ZIP code. Prefills Postal code

ℹ️
Note
When the customer object is provided, the fields on step 2 ("Fill in your details") are prefilled automatically after the customer enters their card (and optionally chooses whether to save it for future use). If customer is not sent, the end user must fill in all fields manually.

For injecting or updating customer data on an existing payment link, see Inject Customer instead.

AllowUsePreregisteredCards only has an effect when a customer object is present in the request, and the only value that should be sent is false. Do not send true — omit the field entirely to get the default (prompt to save card) behavior.

Example Request (with customer prefill)

{
  "amount": 1000,
  "currencyCode": "UYU",
  "paymentType": "checkoutPro",
  "orderNumber": "DEV000111111111111",
  "AllowUsePreregisteredCards": false,
  "installments": [],
  "customer": {
    "identifier": "[email protected]",
    "Email": "[email protected]",
    "firstName": "Sora",
    "lastName": "Mendez",
    "documentTypeId": 4,
    "documentNumber": "42123234",
    "phoneNumber": "541234567821",
    "BillingAddress": {
      "detail": "Rambla 1234",
      "country": "UY",
      "state": "Montevideo",
      "city": "Montevideo",
      "postalCode": "11300"
    },
    "ExternalCustomerId": "CU_1111BambooUY"
  },
  "metadataIn": {
    "invoiceNumber": "17690"
  },
  "OnSuccessResultUrl": "https://www.merchant.com/approved",
  "OnErrorResultUrl": "https://www.merchant.com/rejected",
  "OnCancelResultUrl": "https://www.merchant.com/cancel",
  "LineItems": [
    {
      "title": "Seguro automotriz",
      "Description": "Poliza 1566400",
      "ImageUrl": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcTOe9U5Ok1ZwofQUQOK8WMhhnmC7vOi7NrntQ&s",
      "UnitPrice": 100
    }
  ]
}