Skip to main content
POST
/
payments
Create payment
curl --request POST \
  --url https://api.piriod.com/payments/ \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'x-simple-workspace: <x-simple-workspace>' \
  --data '
{
  "amount": 123,
  "currency": "<string>",
  "date": "2023-12-25",
  "description": "<string>",
  "invoice": "<string>",
  "subscription": "<string>",
  "customer": "<string>",
  "payment_date": "2023-11-07T05:31:56Z",
  "source": 123,
  "sources": [
    123
  ],
  "status": "requires_payment_method",
  "return_url": "<string>",
  "enable_checkout": true,
  "metadata": {}
}
'
{
  "amount": 123,
  "currency": "<string>",
  "date": "2023-12-25",
  "description": "<string>",
  "id": 123,
  "invoice": "<string>",
  "subscription": "<string>",
  "customer": "<string>",
  "balance": 123,
  "payment_date": "2023-11-07T05:31:56Z",
  "source": 123,
  "sources": [
    123
  ],
  "status": "requires_payment_method",
  "failed_reason": "<string>",
  "return_url": "<string>",
  "enable_checkout": true,
  "metadata": {},
  "test_mode": true,
  "created": "2023-11-07T05:31:56Z",
  "updated": "2023-11-07T05:31:56Z"
}

Authorizations

​
Authorization
string
header
required

Use header Authorization: Token <api_token>. API tokens are obtained from the Piriod dashboard.

Headers

​
x-simple-workspace
string
required

Workspace (account) identifier. Required for every request.

​
x-piriod-test-mode
boolean
default:false

Whether to operate against test-mode data. Defaults to false.

Body

application/json
​
amount
number
required
​
currency
string
required

ISO currency code.

​
date
string<date>
required
​
description
string
required
Maximum string length: 256
​
invoice
string | null

Invoice ID this payment applies to.

​
subscription
string | null

Subscription ID when generated by a subscription cycle.

​
customer
string | null
​
payment_date
string<date-time> | null

Effective date the payment was completed.

​
source
integer | null

Primary source ID. (Legacy single source link.)

​
sources
integer[]

All source IDs linked to this payment (multi-source support).

​
status
enum<string>
default:requires_payment_method
Available options:
cancelled,
failed,
incomplete,
processing,
requires_payment_method,
succeeded
​
return_url
string<uri> | null

URL the payer is sent back to after a redirect-flow checkout.

​
enable_checkout
boolean
default:true

Whether the publishable checkout /pay/ is reachable for this payment.

​
metadata
object

Response

Payment created.

​
amount
number
required
​
currency
string
required

ISO currency code.

​
date
string<date>
required
​
description
string
required
Maximum string length: 256
​
id
integer
read-only
​
invoice
string | null

Invoice ID this payment applies to.

​
subscription
string | null

Subscription ID when generated by a subscription cycle.

​
customer
string | null
​
balance
number
read-only

Remaining balance to charge against this payment.

​
payment_date
string<date-time> | null

Effective date the payment was completed.

​
source
integer | null

Primary source ID. (Legacy single source link.)

​
sources
integer[]

All source IDs linked to this payment (multi-source support).

​
status
enum<string>
default:requires_payment_method
Available options:
cancelled,
failed,
incomplete,
processing,
requires_payment_method,
succeeded
​
failed_reason
string | null
read-only

Reason code when status=failed.

​
return_url
string<uri> | null

URL the payer is sent back to after a redirect-flow checkout.

​
enable_checkout
boolean
default:true

Whether the publishable checkout /pay/ is reachable for this payment.

​
metadata
object
​
test_mode
boolean
read-only
​
created
string<date-time>
read-only
​
updated
string<date-time>
read-only