Payments

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 no fee: your account receives the full amount, less Stripe’s own processing fees. 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.

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.

POST

payment_requests

Create a payment request

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,
  "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,
  "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,
  "a2ui_errors": [
    {
      "part_index": 123,
      "data_index": 123,
      "a2ui_message": {
        "version": "v0.9.1",
        "error": {
          "code": "VALIDATION_FAILED",
          "surfaceId": "<string>",
          "path": "<string>",
          "message": "<string>"
        }
      }
    }
  ],
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "a2ui_errors": [
    {
      "part_index": 123,
      "data_index": 123,
      "a2ui_message": {
        "version": "v0.9.1",
        "error": {
          "code": "VALIDATION_FAILED",
          "surfaceId": "<string>",
          "path": "<string>",
          "message": "<string>"
        }
      }
    }
  ],
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "a2ui_errors": [
    {
      "part_index": 123,
      "data_index": 123,
      "a2ui_message": {
        "version": "v0.9.1",
        "error": {
          "code": "VALIDATION_FAILED",
          "surfaceId": "<string>",
          "path": "<string>",
          "message": "<string>"
        }
      }
    }
  ],
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "a2ui_errors": [
    {
      "part_index": 123,
      "data_index": 123,
      "a2ui_message": {
        "version": "v0.9.1",
        "error": {
          "code": "VALIDATION_FAILED",
          "surfaceId": "<string>",
          "path": "<string>",
          "message": "<string>"
        }
      }
    }
  ],
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "a2ui_errors": [
    {
      "part_index": 123,
      "data_index": 123,
      "a2ui_message": {
        "version": "v0.9.1",
        "error": {
          "code": "VALIDATION_FAILED",
          "surfaceId": "<string>",
          "path": "<string>",
          "message": "<string>"
        }
      }
    }
  ],
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "a2ui_errors": [
    {
      "part_index": 123,
      "data_index": 123,
      "a2ui_message": {
        "version": "v0.9.1",
        "error": {
          "code": "VALIDATION_FAILED",
          "surfaceId": "<string>",
          "path": "<string>",
          "message": "<string>"
        }
      }
    }
  ],
  "trace_id": "<string>"
}

Authorizations

Authorization

string

header

required

Bearer token authentication. Include your API token in the Authorization header.

Format: Authorization: Bearer <your-token>

Headers

Idempotency-Key

string

Reusing a key with the same body returns the first request (200); with a different body, 409.

Required string length: 1 - 255

Body

application/json

description

string

required

The card's title line and the checkout's product name. Trimmed; 1 to 32 characters.

Required string length: 1 - 32

Response

The same Idempotency-Key and body were used before; the first request is returned.

string<uuid>

required

object

enum<string>

required

Available options:

payment_request

status

enum<string>

required

A payment request's lifecycle. It leaves requested exactly once, and only on Stripe's word or your cancel.

Available options:

requested,

succeeded,

canceled,

expired

mode

enum<string>

required

Available options:

payment,

subscription

amount

integer

required

What the person is charged at checkout, in minor units. In subscription mode, what the first period costs after any discount.

currency

string

required

description

string

required

category

enum<string>

required

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 code 2006). A tip to an agent or a creator is digital_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…").

Available options:

physical_goods,

digital_goods,

donation

checkout_url

string

required

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.

expires_at

string<date-time>

required

When the request stops accepting payment and moves to expired, 23 hours after it was created.

metadata

object

required

Show child attributes

stripe

object

required

The ids of the Stripe objects on your connected account, your join keys into your own Stripe Dashboard, API and webhooks.

Show child attributes

created_at

string<date-time>

required

updated_at

string<date-time>

required

image_url

string

The product picture, on Relay's image host. Absent without one.

price_id

string

Subscription mode.

quantity

integer

Subscription mode.

interval

enum<string>

Subscription mode.

Available options:

day,

week,

month,

year

interval_count

integer

Subscription mode.

discount

object

Subscription mode only. One coupon or one promotion code from your connected Stripe account, never both.

Show child attributes

paid_at

string<date-time>

Absent until the request succeeds.

Create a payment request

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,
  "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,
  "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,
  "a2ui_errors": [
    {
      "part_index": 123,
      "data_index": 123,
      "a2ui_message": {
        "version": "v0.9.1",
        "error": {
          "code": "VALIDATION_FAILED",
          "surfaceId": "<string>",
          "path": "<string>",
          "message": "<string>"
        }
      }
    }
  ],
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "a2ui_errors": [
    {
      "part_index": 123,
      "data_index": 123,
      "a2ui_message": {
        "version": "v0.9.1",
        "error": {
          "code": "VALIDATION_FAILED",
          "surfaceId": "<string>",
          "path": "<string>",
          "message": "<string>"
        }
      }
    }
  ],
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "a2ui_errors": [
    {
      "part_index": 123,
      "data_index": 123,
      "a2ui_message": {
        "version": "v0.9.1",
        "error": {
          "code": "VALIDATION_FAILED",
          "surfaceId": "<string>",
          "path": "<string>",
          "message": "<string>"
        }
      }
    }
  ],
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "a2ui_errors": [
    {
      "part_index": 123,
      "data_index": 123,
      "a2ui_message": {
        "version": "v0.9.1",
        "error": {
          "code": "VALIDATION_FAILED",
          "surfaceId": "<string>",
          "path": "<string>",
          "message": "<string>"
        }
      }
    }
  ],
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "a2ui_errors": [
    {
      "part_index": 123,
      "data_index": 123,
      "a2ui_message": {
        "version": "v0.9.1",
        "error": {
          "code": "VALIDATION_FAILED",
          "surfaceId": "<string>",
          "path": "<string>",
          "message": "<string>"
        }
      }
    }
  ],
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "a2ui_errors": [
    {
      "part_index": 123,
      "data_index": 123,
      "a2ui_message": {
        "version": "v0.9.1",
        "error": {
          "code": "VALIDATION_FAILED",
          "surfaceId": "<string>",
          "path": "<string>",
          "message": "<string>"
        }
      }
    }
  ],
  "trace_id": "<string>"
}

Overview

Chats

Messages

Attachments

Contacts

Webhooks

WebSocket

Agents

Calls

Payments

Tasks

Communities

Create a payment request

Authorizations

Headers

Body

Response