Link-to-Pay and the A2A InstaPay network

Ask anyone on A2A InstaPay to pay, pay requests from outside your app, and pay A2A InstaPay merchants by QR code.

Your customers reach the whole A2A InstaPay network, not only each other. A request to pay can go to a customer of yours or to any A2A InstaPay mobile number, and a request can arrive from someone outside your app.

Ask someone to pay#

Shell

curl -X POST https://sandbox.a2ainstapay.com/v1/link-to-pay-requests -H "Authorization: Bearer $A2A_ACCESS_TOKEN" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" -d '{"requester_customer_id":"cus_...","payer_mobile_number":"+12025550101","amount":2500,"reason":"Dinner"}'

Name the payer with payer_customer_id (one of your customers) or payer_mobile_number (anyone on A2A InstaPay), not both. A consumer can ask consumers; a merchant can ask consumers and merchants. A payer who cannot receive requests gives 422 payer_not_eligible.

Check a number first with GET /v1/payer-lookup?mobile_number=...: can_receive says whether a request can be sent, and customer_id names your customer with that number. The lookup is limited to 20 a minute and 10 per number.

Status	Meaning
`pending`	Waiting for the payer (seven days)
`processing`	A payment of the request is being confirmed
`paid`	Paid; `paid_amount` and `payment_id` are set
`declined`	The payer declined (`POST /v1/link-to-pay-requests/{id}/decline`, for your payers)
`canceled`	The requester canceled (`POST /v1/link-to-pay-requests/{id}/cancel`, for your requesters)
`expired`	Not paid in time

link_to_pay_request.created, .paid, .declined, .canceled and .expired report each change. List a customer's requests with GET /v1/link-to-pay-requests?customer_id=...&role=payer or role=requester.

Pay a request#

The payer pays from balance with a payment that names the request. The amount may be lower than requested, never higher.

Shell

curl -X POST https://sandbox.a2ainstapay.com/v1/payments -H "Authorization: Bearer $A2A_ACCESS_TOKEN" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" -d '{"payer_customer_id":"cus_...","source":"balance","link_to_pay_request_id":"ltp_...",
    "customer_authentication":{"methods":["password"],"authenticated_at":"2026-10-16T14:02:11Z"}}'

The payment's type is consumer_to_consumer when a consumer asked, consumer_to_merchant or merchant_to_merchant when a merchant asked. Quote it first with POST /v1/quotes and type link_to_pay_payment.

Parties outside your app#

Payments and requests carry a payer and a payee party. A party outside your app has customer_id null, with a display name and the last four digits of the mobile number. A payment from outside has payer_customer_id null; a payment to outside has payee_customer_id null. Money that arrives from outside, or leaves to it, moves through the A2A InstaPay network.

Pay an A2A InstaPay merchant#

A customer can pay any A2A InstaPay merchant by scanning its QR code. Send the code as qr_payload with the amount; the code carries no amount. Payments to merchants outside your app are made from balance. Your own merchants' payment requests (A2AQR1...) work as before.

In the sandbox#

The sandbox has four A2A InstaPay users outside your workspace, listed in Test data. Requests to them are answered by the amount's cents after a few seconds: 01 declines, 02 waits until it expires, anything else is paid. Send a request or a payment from outside with the simulation events link_to_pay_request.created and payment.received. Run the scenarios Link-to-Pay between two customers and Link-to-Pay across the A2A InstaPay network.

Questions about this page? Contact developer support.