Create Checkout Session API (Draft)
Draft
This document describes a proposed API contract for
Pay with Pyng. It is not final and may change before public release.
API is used by the partner to create a Checkout Session for Pay with Pyng.
After a successful response, the partner receives a Launch URL which should be opened when the user clicks the Pay with Pyng button.
URL path - /checkout/{siteId}/session
Method - POST
Request Headers
| Header Name | Header Value | Notes |
|---|---|---|
| Content-Type | application/json | |
| Authorization | Bearer access_token | Access token must have an appropriate scope to access resource |
| Idempotency-Key | string | Required for safe retries |
Path Parameters
| Parameter Key | Parameter Data Type | Notes |
|---|---|---|
| siteId | string | Unique site id assigned to the partner's site |
Body Parameters
| Parameter Key | Parameter Data Type | Required | Notes |
|---|---|---|---|
| orderId | string | Y | Unique partner order identifier |
| amount | integer | Y | Amount in cents |
| returnTarget | object | Y | Structured return target |
| cancelTarget | object | Y | Structured cancel target |
| expiresInSeconds | integer | N | Requested session lifetime |
| lineItems | array | N | Optional itemized purchase details |
| metadata | object | N | Optional partner metadata |
ReturnTarget / CancelTarget
| Parameter Key | Parameter Data Type | Required | Notes |
|---|---|---|---|
| type | string | Y | One of web, app |
| url | string | Y | Registered website or app target |
Response
Status Code - 201 Created
| Parameter Key | Parameter Data Type | Required | Notes |
|---|---|---|---|
| data | object | Y | Checkout Session data |
| traceId | string | Y | Unique identifier of the request |
Checkout Session Response
| Parameter Key | Parameter Data Type | Required | Notes |
|---|---|---|---|
| checkoutSessionId | string | Y | Unique Checkout Session id |
| launchUrl | string | Y | URL opened by partner UI |
| status | string | Y | Initial session status |
| expiresAt | string | Y | Session expiry timestamp |
| orderId | string | Y | Echo of partner order id |
| siteId | string | Y | Echo of partner site id |
Notes
currencyis not required in version 1 draft.- Hosted Checkout and return behavior are defined in RFC 0010.
- Redirect return is not the source of truth for payment completion.
- Hosted Checkout uses a configured timeout. When the session times out, the Checkout Session moves to
Expired. - If a valid
returnTargetis present, Pyng attempts to return the user to the merchant app or site after timeout.