Create a payment request

POST 
/api/payment_requests

Requires the PAYPAL OAuth scope. Create a draft payment request for a selected contact. You can upload attachments before finalizing it via /payment_requests/{id}/activate.

Request

Header Parameters

Unique-Request-Id string

Possible values: <= 50 characters

An optional unique identifier for the request, limited to 50 characters. Used to track requests and prevent duplication.

application/json

Body

required

contactId integernullable

Possible values: > 0

contact object
Alternative recipient definition when contactId is not provided.
name stringrequired
countryCode stringrequired
type string
email email
amount stringnullablerequired

Possible values: Value must match regular expression ^(\d+(\.\d{1,2})?)$

currencyCode stringnullablerequired

Possible values: >= 3 characters and <= 3 characters

invoiceReference stringnullable

Possible values: <= 255 characters

invoiceDate stringnullablerequired
dueDate stringnullablerequired
message stringnullable
reminderEnabled boolean
tagIds integer[]
deliveryChannel stringrequired

Possible values: [email_and_url, url_only]

Default value: email_and_url

email emailnullable

Responses

201

Created - The request was processed successfully.

application/json

Schema

Schema

id integer
contactId integer
currencyCode string
amount string
invoiceReference stringnullable
invoiceDate stringnullable
dueDate stringnullable
message stringnullable
reminderEnabled boolean
tagIds integer[]
email stringnullable
pending boolean

Default value: true

draft boolean
hash string
paymentPageUrl stringnullable

Example (from schema)

{
  "id": 42,
  "contactId": 145,
  "currencyCode": "CHF",
  "amount": "5000.50",
  "invoiceReference": "Invoice INV-2026-001",
  "invoiceDate": "2026-04-21",
  "dueDate": "2026-05-01",
  "message": "Please settle this invoice until due date.",
  "reminderEnabled": true,
  "tagIds": [
    1,
    2,
    3
  ],
  "email": "recipient@example.com",
  "pending": true,
  "draft": false,
  "hash": "a5eb1c1f-a4ad-4a19-ad72-f57ba5acf795",
  "paymentPageUrl": "https://www.paypal.com/checkoutnow?token=XYZ"
}

400

Bad Request -- Your request is invalid.

application/json

Schema

Schema

title stringnullable

A short, human-readable summary of the problem.

detail stringnullable

A human-readable explanation specific to this occurrence of the problem.

status numbernullable

Default value: 400

instance stringnullable

A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

type string

A URI reference that identifies the problem type

Example (from schema)

{
  "title": "string",
  "detail": "string",
  "status": 400,
  "instance": "string",
  "type": "string"
}

401

Unauthorised -- Your access token is wrong.

application/json

Schema

Schema

type string
title string
detail string

Example (from schema)

{
  "type": "string",
  "title": "string",
  "detail": "string"
}

403

Forbidden -- Access to the requested resource or action is forbidden.

application/json

Schema

Schema

title stringnullable

A short, human-readable summary of the problem.

detail stringnullable

A human-readable explanation specific to this occurrence of the problem.

status numbernullable

Default value: 400

instance stringnullable

A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

type string

A URI reference that identifies the problem type

Example (from schema)

{
  "title": "string",
  "detail": "string",
  "status": 400,
  "instance": "string",
  "type": "string"
}

422

Unprocessable Content -- We could not process your request due to invalid data provided.

application/json

Schema

Schema

status integer

Default value: 422

violations object[]
Array [
propertyPath stringrequired
The property path of the violation
message stringrequired
The message associated with the violation
code string
The code of the violation
hint string
An extra hint to understand the violation
payload object
The serialized payload of the violation
property name* any
The serialized payload of the violation
]
detail string
type string
title stringnullable
instance stringnullable

Example (from schema)

{
  "status": 422,
  "violations": [
    {
      "propertyPath": "string",
      "message": "string",
      "code": "string",
      "hint": "string",
      "payload": {}
    }
  ],
  "detail": "string",
  "type": "string",
  "title": "string",
  "instance": "string"
}

Loading...