Create payment link

post

https://sandbox.dev.business.mamopay.com/manage_api/v1/links

Creates a hosted payment link you can send to a customer or embed in your site. A link can take a one-off payment, be reused up to its capacity, or bill a customer on a schedule when you attach a subscription. The response includes the link's id and the payment_url to send your customer to.

Confirming the payment

When the customer finishes paying, Mamo redirects them to your return_url (or failure_return_url on failure) with these query params appended:

Param	Meaning
`transactionId`	The payment ID
`chargeUID`	The payment ID (same value as `transactionId`)
`paymentLinkId`	The payment link ID
`createdAt`	When the payment was created, `YYYY-MM-DD-HH-MM-SS`, UAE time
`status`	The payment status, e.g. `captured` or `failed`

Each key of the link's custom_data is appended too, and can overwrite the names above.

Sample redirect after a successful payment:

https://example.com/paymentSuccess?chargeUID=PAY-2B3C4D5E6F&createdAt=2023-08-09-16-42-35&paymentLinkId=MB-LINK-6F7A8B9C0D&status=captured&transactionId=PAY-2B3C4D5E6F

🚧
Don't trust the redirect params
They're appended client-side and can be tampered with or missed. Confirm the final status server-side with a webhook, Fetch payment info, or Fetch payment link info.

Testing in the sandbox

Pay a sandbox link with the cards in Sandbox testing → Test cards, which cover successful and failed payments, with and without 3DS.

Subscriptions

To bill a customer on a schedule, create the subscription first with Create subscription, then pass its identifier as subscription_id with link_type set to inline.

📘
Inline subscription object
You can configure the schedule inline with the subscription object instead. If it sets both end_date and payment_quantity, end_date takes precedence. We recommend subscription_id.

Recipes

💳

Accept a payment with a payment link

Open Recipe

✅

Accept a payment and confirm it with a webhook

Open Recipe

📱

Add Apple Pay and Google Pay

Open Recipe

🔒

Hold a payment, capture it later, and refund

Open Recipe

🏪

Run a marketplace: collect, hold, split and pay sellers

Open Recipe

🧪

Get sandbox access and make your first test payment

Open Recipe

Body Params

title

string

required

length between 1 and 50

Defaults to Chocolate Box - Small

The title of the payment link

description

string

length ≤ 75

Defaults to 12pcs Chocolate Box

Payment description. This will appear on the payment checkout page.

capacity

integer

The number of times a payment link can be used, if null the link can be used indefinitely. The capacity will be ignored when the subscription params exist.

return_url

uri

Defaults to https://example.com/paymentSuccess

The URL which the customer will be redirected to after a successful payment.

failure_return_url

uri

Defaults to https://example.com/paymentFailure

The URL which the customer will be redirected to after a failed payment.

terms_and_conditions_url

uri

The URL to the terms and conditions page, if provided, the customer will be required to accept the terms before proceeding to payment.

processing_fee_percentage

number

0 to 5

Processing fee that you as a merchant can impose on your customers, as a percentage of the amount. Send this or processing_fee_amount, not both.

processing_fee_amount

number

Processing fee that you as a merchant can impose on your customers, as a fixed amount in the link's amount_currency. Send this or processing_fee_percentage, not both.

amount

number

≥ 2

Defaults to 119.99

amount could be 0 with save_card 'required' option for card verification

max_amount

number

Leave amount out and set this to let the customer enter the amount, up to this cap. Can't be sent together with amount, and must be greater than 0.

amount_currency

string

Defaults to AED

Currency code for the payment amount. Accepted currencies are configured by Mamo and can change; see Supported currencies for the current list. Tabby is available for AED only, American Express cards can pay in AED or USD only, and hold_and_charge_later supports a narrower set of currencies.

link_type

string

enum

Defaults to standalone

Type of link to be created.

Allowed:

enable_tabby

boolean

Defaults to false

Enables the ability for customers to buy now and pay later.

enable_message

boolean

Defaults to false

Enables the ability for customers to add a message during the checkout process.

enable_tips

boolean

Defaults to false

Enables the tips option. This will be displayed on the first screen.

save_card

string

enum

Defaults to off

Saves the customer's card so you can charge it later with Initiate payment. required always saves it, optional lets the customer tick a box, and required_without_checkbox saves it without showing the box. Send a string: a JSON boolean such as true returns 422.

Allowed:

enable_customer_details

boolean

Defaults to false

Enables adding customer details such as the name, email, and phone number. This screen will be displayed before the payment details screen.

enable_quantity

boolean

Defaults to false

When enabled, customers can specify the number of items they intend to purchase. This quantity will serve as a multiplier for the base amount.

send_customer_receipt

boolean

Defaults to true

Enables the sending of customer receipts.

payment_methods

array

Accepted payment methods: card, and wallet for Apple Pay and Google Pay. Wallets are on by default: if you omit payment_methods, links in a wallet-supported currency accept card and wallet. Send ["card"] to turn wallets off.

payment_methods

rules

object

Setting the rule for payment link

subscription_id

string

The identifier of an existing subscription (created via the Create subscription API) to attach to this payment link. This is the recommended way to create a subscription payment link — create the subscription first, then pass its identifier here. Requires link_type to be inline. An unknown ID is ignored and a one-off link is created.

subscription

object

Inline subscription configuration, to be populated if this payment link is for a subscription. Otherwise, this property can be left out. We recommend creating the subscription with the Create Subscription API and passing its subscription_id instead.

first_name

string

Top-level prefill field. The customer's first name, stored in the link's prefilled_customer and pre-populated at checkout. Note: prefill is driven only by these top-level first_name, last_name, email and phone_number fields — the prefilled_customer object is returned in responses but is ignored if sent in the request body.

last_name

string

Top-level prefill field. The customer's last name, stored in the link's prefilled_customer and pre-populated at checkout.

string

Top-level prefill field. The customer's email, stored in the link's prefilled_customer and pre-populated at checkout.

phone_number

string

Top-level prefill field. The customer's phone number, stored in the link's prefilled_customer and pre-populated at checkout.

custom_data

object

Your own key-value data, up to 5 keys. It is returned on payments made through this link and appended to the redirect URLs.

external_id

string

The external ID of your choice to associate with payments captured by this payment link.

expiration_date

string

A future date after which the link stops accepting payments, for example 2026-12-31.

lang

string

enum

Defaults to en

Language of the checkout page.

Allowed:

internal_note

string

A note for your team. It isn't shown to the customer.

hold_and_charge_later

boolean

Defaults to false

Indicates whether to place the payment on hold and charge it later using the "captures" API.

payouts_share

object

Optional split that routes part of each payment to a recipient. Omit this object entirely when the payment should not be split — there is no numeric value that means 'no split'. When present, you must supply recipient_id, recipient_pays_fees, and exactly one of percentage_to_recipient or amount_to_recipient (not both). There is no release_date input: if you send one it is ignored, and the response's payouts_share.release_date is null.

Headers

Idempotency-Key

string

A unique key, such as a UUID, that makes it safe to retry this request. Reuse the same key when you retry. See Idempotency.

Responses

404

Invalid request

429

Too many requests. You sent more than 100 requests in 30 seconds from one IP address. This response has no JSON body. See Rate limits.

500

Unexpected error

201Successful response

403Unauthorised

422Unprocessable entity