Retrieve a payment request - Relay

GET

/

v1

/

payment_requests

/

{paymentRequestId}

Retrieve a payment request

curl --request GET \
  --url https://api.relayapp.im/v1/payment_requests/{paymentRequestId} \
  --header 'Authorization: Bearer <token>'

{
  "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>"
}

Authorizations

Authorization

string

header

required

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

Format: Authorization: Bearer <your-token>

Path Parameters

paymentRequestId

string<uuid>

required

Response

The payment request

id

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

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 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.

Retrieve a payment request

curl --request GET \
  --url https://api.relayapp.im/v1/payment_requests/{paymentRequestId} \
  --header 'Authorization: Bearer <token>'

{
  "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>"
}