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.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
Headers
Body
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 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 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.
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 curl --request POST \
--url https://api.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>"
}
