Create a payment request
Create a payment request and get back the checkout_url, Relay’s pay
page for it. Relay creates one Stripe PaymentIntent on your
organization’s own connected Stripe account, as a direct charge (in
subscription mode, an incomplete Subscription whose first-period
PaymentIntent is that one object): the money settles to your Stripe
account, you are the merchant of record, and Relay never holds the
funds. Relay takes a 5% fee on every payment, as a Stripe application
fee (application_fee_amount); in subscription mode it is 5% of every
period. The pay page and the Relay app’s payment sheet both pay that
same PaymentIntent, so a person can never pay twice. Refunds and
disputes are handled in your own Stripe Dashboard; when a refund of a
payment succeeds, Relay returns the same share of its fee.
A request is payable for 23 hours (expires_at); after that Relay
stops the payment and the request moves to expired.
Send the request to a person as a payment message part. Its status
moves only on Stripe’s word: payment.succeeded, payment.canceled
and payment.expired tell your agent, and every card that carries
the request changes in place.
Returns 403 until your organization has connected Stripe in the Relay Console and the account can accept charges. Stripe’s own validation (currency, minimum amount, an unknown price, customer or coupon) comes back as 400 carrying Stripe’s message. Returns 503 while payments are not available on this server.
curl --request POST \
--url https://api.staging.relayapp.im/v1/payment_requests \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"description": "<string>"
}
'{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"object": "payment_request",
"status": "requested",
"mode": "payment",
"amount": 123,
"application_fee_amount": 123,
"currency": "<string>",
"description": "<string>",
"category": "physical_goods",
"checkout_url": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"metadata": {},
"stripe": {
"payment_intent_id": "<string>",
"customer_id": "<string>",
"subscription_id": "<string>"
},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"image_url": "<string>",
"price_id": "<string>",
"quantity": 123,
"interval": "day",
"interval_count": 123,
"discount": {
"coupon": "<string>",
"promotion_code": "<string>",
"label": "<string>"
},
"paid_at": "2023-11-07T05:31:56Z"
}{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"object": "payment_request",
"status": "requested",
"mode": "payment",
"amount": 123,
"application_fee_amount": 123,
"currency": "<string>",
"description": "<string>",
"category": "physical_goods",
"checkout_url": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"metadata": {},
"stripe": {
"payment_intent_id": "<string>",
"customer_id": "<string>",
"subscription_id": "<string>"
},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"image_url": "<string>",
"price_id": "<string>",
"quantity": 123,
"interval": "day",
"interval_count": 123,
"discount": {
"coupon": "<string>",
"promotion_code": "<string>",
"label": "<string>"
},
"paid_at": "2023-11-07T05:31:56Z"
}{
"error": {
"status": 123,
"code": 123,
"message": "<string>",
"doc_url": "<string>",
"retry_after": 123
},
"success": true,
"trace_id": "<string>"
}{
"error": {
"status": 123,
"code": 123,
"message": "<string>",
"doc_url": "<string>",
"retry_after": 123
},
"success": true,
"trace_id": "<string>"
}{
"error": {
"status": 123,
"code": 123,
"message": "<string>",
"doc_url": "<string>",
"retry_after": 123
},
"success": true,
"trace_id": "<string>"
}{
"error": {
"status": 123,
"code": 123,
"message": "<string>",
"doc_url": "<string>",
"retry_after": 123
},
"success": true,
"trace_id": "<string>"
}{
"error": {
"status": 123,
"code": 123,
"message": "<string>",
"doc_url": "<string>",
"retry_after": 123
},
"success": true,
"trace_id": "<string>"
}{
"error": {
"status": 123,
"code": 123,
"message": "<string>",
"doc_url": "<string>",
"retry_after": 123
},
"success": true,
"trace_id": "<string>"
}Authorizations
Bearer token authentication. Include your API token in the Authorization header.
Format: Authorization: Bearer <your-token>
Headers
Reusing a key with the same body returns the first request (200); with a different body, 409.
1 - 255Body
The card's title line and the checkout's product name. Trimmed; 1 to 32 characters.
1 - 32What is being paid for, the same three values as PayPal Orders v2 items[].category (PHYSICAL_GOODS, DIGITAL_GOODS, DONATION; developer.paypal.com/docs/api/orders/v2/). The App Store Review Guidelines (developer.apple.com/app-store/review/guidelines/) decide where each can be paid:
physical_goods: physical goods, and services used in the real world, such as a haircut or a ride (3.1.3(e)). Payable anywhere.digital_goods: anything used in an app or online. A person pays by opening the link in Safari, and only on the United States storefront (3.1.1(a)); sending one to a person whose devices report only other storefronts returns 422 (error code2006). A tip to an agent or a creator isdigital_goods(3.1.1: tips to digital content providers use In-App Purchase).donation: money for a charity or a fundraiser. Collected outside the app, on any storefront (3.2.2(iv): such apps "may only collect funds outside of the app, such as via Safari…").
physical_goods, digital_goods, donation Payment mode (required there). What to charge, in the currency's minor units; Stripe's minimum and maximum apply. Omit in subscription mode.
Payment mode (required there). A 3-letter ISO 4217 code, returned lowercase. Omit in subscription mode; the price carries it.
^[A-Za-z]{3}$Up to 49 keys of your own, returned on the request and on every payment.* event, and stamped on the Stripe objects created on your account. Keys starting with relay_ are reserved; Relay adds relay_payment_request_id.
Show child attributes
Show child attributes
payment collects one charge of amount in currency. subscription starts an auto-renewing subscription from a recurring price_id on your connected Stripe account; the person pays the first period at checkout and Stripe renews it from then on.
payment, subscription Subscription mode (required there). An active recurring Price on your connected Stripe account.
Subscription mode only. Units of the price. Defaults to 1.
x >= 1An existing Customer on your connected Stripe account (cus_...) to attach the request to.
Subscription mode only. One coupon or one promotion code from your connected Stripe account, never both.
Show child attributes
Show child attributes
Optional product picture, an HTTPS address, like Telegram sendInvoice photo_url (core.telegram.org/bots/api#sendinvoice). Relay copies it into its own image store, the way it stores agent pictures, and returns Relay's address. Shown on the card and on the pay page.
2048Response
The same Idempotency-Key and body were used before; the first request is returned.
payment_request A payment request's lifecycle. It leaves requested exactly once, and only on Stripe's word or your cancel.
requested, succeeded, canceled, expired payment, subscription What the person is charged at checkout, in minor units. In subscription mode, what the first period costs after any discount.
Relay's 5% fee on amount, in minor units, taken from the payment by Stripe; in subscription mode, the first period's fee. 0 when 5% rounds to nothing.
What is being paid for, the same three values as PayPal Orders v2 items[].category (PHYSICAL_GOODS, DIGITAL_GOODS, DONATION; developer.paypal.com/docs/api/orders/v2/). The App Store Review Guidelines (developer.apple.com/app-store/review/guidelines/) decide where each can be paid:
physical_goods: physical goods, and services used in the real world, such as a haircut or a ride (3.1.3(e)). Payable anywhere.digital_goods: anything used in an app or online. A person pays by opening the link in Safari, and only on the United States storefront (3.1.1(a)); sending one to a person whose devices report only other storefronts returns 422 (error code2006). A tip to an agent or a creator isdigital_goods(3.1.1: tips to digital content providers use In-App Purchase).donation: money for a charity or a fundraiser. Collected outside the app, on any storefront (3.2.2(iv): such apps "may only collect funds outside of the app, such as via Safari…").
physical_goods, digital_goods, donation Relay's pay page for this request, https://pay.relayapp.im/<token>. Anyone holding it can pay the request. Send it back unchanged in a payment part.
When the request stops accepting payment and moves to expired, 23 hours after it was created.
Show child attributes
Show child attributes
The ids of the Stripe objects on your connected account, your join keys into your own Stripe Dashboard, API and webhooks.
Show child attributes
Show child attributes
The product picture, on Relay's image host. Absent without one.
Subscription mode.
Subscription mode.
Subscription mode.
day, week, month, year Subscription mode.
Subscription mode only. One coupon or one promotion code from your connected Stripe account, never both.
Show child attributes
Show child attributes
Absent until the request succeeds.
curl --request POST \
--url https://api.staging.relayapp.im/v1/payment_requests \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"description": "<string>"
}
'{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"object": "payment_request",
"status": "requested",
"mode": "payment",
"amount": 123,
"application_fee_amount": 123,
"currency": "<string>",
"description": "<string>",
"category": "physical_goods",
"checkout_url": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"metadata": {},
"stripe": {
"payment_intent_id": "<string>",
"customer_id": "<string>",
"subscription_id": "<string>"
},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"image_url": "<string>",
"price_id": "<string>",
"quantity": 123,
"interval": "day",
"interval_count": 123,
"discount": {
"coupon": "<string>",
"promotion_code": "<string>",
"label": "<string>"
},
"paid_at": "2023-11-07T05:31:56Z"
}{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"object": "payment_request",
"status": "requested",
"mode": "payment",
"amount": 123,
"application_fee_amount": 123,
"currency": "<string>",
"description": "<string>",
"category": "physical_goods",
"checkout_url": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"metadata": {},
"stripe": {
"payment_intent_id": "<string>",
"customer_id": "<string>",
"subscription_id": "<string>"
},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"image_url": "<string>",
"price_id": "<string>",
"quantity": 123,
"interval": "day",
"interval_count": 123,
"discount": {
"coupon": "<string>",
"promotion_code": "<string>",
"label": "<string>"
},
"paid_at": "2023-11-07T05:31:56Z"
}{
"error": {
"status": 123,
"code": 123,
"message": "<string>",
"doc_url": "<string>",
"retry_after": 123
},
"success": true,
"trace_id": "<string>"
}{
"error": {
"status": 123,
"code": 123,
"message": "<string>",
"doc_url": "<string>",
"retry_after": 123
},
"success": true,
"trace_id": "<string>"
}{
"error": {
"status": 123,
"code": 123,
"message": "<string>",
"doc_url": "<string>",
"retry_after": 123
},
"success": true,
"trace_id": "<string>"
}{
"error": {
"status": 123,
"code": 123,
"message": "<string>",
"doc_url": "<string>",
"retry_after": 123
},
"success": true,
"trace_id": "<string>"
}{
"error": {
"status": 123,
"code": 123,
"message": "<string>",
"doc_url": "<string>",
"retry_after": 123
},
"success": true,
"trace_id": "<string>"
}{
"error": {
"status": 123,
"code": 123,
"message": "<string>",
"doc_url": "<string>",
"retry_after": 123
},
"success": true,
"trace_id": "<string>"
}