Creating a Payment Request

Overview

After a user has registered with SynchPay, you can request money from them by creating a payment request through the /payment/create endpoint. This endpoint allows you to charge the user for services rendered or products provided.

How It Works

Obtain an Access Token

Before calling /payment/create, secure an access token by making a POST request to /auth/token using your ClientId and ClientSecret.

Submit a Payment Request

With the access token, send a JSON payload to the /payment/create endpoint. The request identifies the payer and the company location, and specifies the payment amount in cents.

Processing the Request

Once the payment request is submitted, the consumer receives a prompt through the SynchPay app to choose a payment method and approve the transaction. Depending on the configuration, the payer may be able to pay via bank account (A2A) or credit card.

Receive Payment Confirmation

After the consumer confirms the payment, SynchPay processes the transaction and sends a webhook to your backend containing all relevant payment details.

Creating the Payment Request

The /payment/create endpoint enables you to initiate a payment request by submitting a structured JSON object.

Endpoint

URL: https://api.synchpay.com/payment/create
Method: POST
Authorization: Bearer <AccessToken>Note: Obtain the access token from /auth/token using your ClientId and ClientSecret.

Header Parameters

Parameter	Type	Description	Required
`Idempotency-Key`	string	A client-generated key that identifies the request.	No

Request Body

The JSON payload sent to the endpoint must include the following fields:

Parameter	Type	Description	Required
`RegistrationId`	string	The unique user registration ID from `/user/register`. Required when `ContactNumber` is omitted.	No *
`ContactNumber`	string	The payer’s phone number in international format. Required when `RegistrationId` is omitted.	No *
`EmailAddress`	string	Email address for notifications.	No
`LocationId`	string	The UUID of the company location receiving the payment. See company locations.	Yes
`Amount`	integer	The payment amount in cents. For example, $50.00 is `5000`.	Yes
`ShortDescription`	string	A brief description of the service or product.	No
`FeePayer`	string	Who covers the fee: `"client"`, `"partner"`, or `"ask"`. With `"ask"`, the payer chooses while accepting the request.	Yes
`Reference`	string	A reference from your external system, such as a payment ID.	No
`Attachment`	string	A PDF attachment encoded as Base64.	No
`DueDate`	string	The due date in `YYYY-MM-DD` format.	No
`EnableDebitAuth`	boolean	Sends a debit authorization request to the payer. Alias for `EnableAutoPay`.	No
`DebitAuthLimit`	integer	Debit authorization limit in cents. Alias for `AutoPayLimit`.	No
`EnableAutoPay`	boolean	Asks the payer for auto-pay consent. Alias for `EnableDebitAuth`.	No
`AutoPayLimit`	integer	Auto-pay limit in cents. Alias for `DebitAuthLimit`.	No
`Metadata`	object	A flat object containing string metadata values.	No
`ReturnUrl`	string	URL to which SynchPay redirects the payer after the payment flow.	No
`OneTimePayment`	boolean	Whether the request represents a one-time payment.	No

* Either RegistrationId or ContactNumber have to be specified.

EnableDebitAuth / DebitAuthLimit and EnableAutoPay / AutoPayLimit are interchangeable — you only need to provide one pair. If both are provided, the EnableDebitAuth and DebitAuthLimit values take precedence. See debit authorization for more details on how debit auth works.

Example Request

{
  "RegistrationId": "6e8d9257-bd5f-45cf-8f29-6d0ae8a6d991",
  "LocationId": "4d8ab11b-0322-4bf9-921f-39d753b0530c",
  "Amount": 5000,
  "ShortDescription": "Additional services rendered.",
  "FeePayer": "partner",
  "EnableAutoPay": true,
  "AutoPayLimit": 10000,
  "Metadata": {
    "additionalProp1": "foo",
    "additionalProp2": "bar"
  }
}

Response

Upon successful processing, the API returns a JSON object with details about the created payment request:

{
  "PaymentRequestId": "ce0e3549-a83e-4cf6-bb5c-1d50a21d8af7",
  "AccountMask": "0000",
  "Url": "https://app.synchpay.com/payment/ce0e3549-a83e-4cf6-bb5c-1d50a21d8af7",
  "RegistrationPersonId": "27420540-dbbf-44be-b773-2014851787b7"
}

Field	Type	Description
`PaymentRequestId`	string	The UUID of the created payment request.
`AccountMask`	string	The masked account identifier, when available.
`Url`	string	URL for completing the payment flow.
`RegistrationPersonId`	string	The registered person UUID created or resolved for the payer, when present.

Payment Confirmation

After the consumer approves the payment request via their registered bank account, credit card, or the SynchPay app, the transaction is processed. SynchPay then sends a webhook to your backend with the following information:

{
  "PaymentRequestId": "ce0e3549-a83e-4cf6-bb5c-1d50a21d8af7",
  "RegistrationId": "6e8d9257-bd5f-45cf-8f29-6d0ae8a6d991",
  "Amount": 5000,
  "Currency": "USD",
  "Status": "Processing",
  "Timestamp": "2024-08-09T12:34:56Z",
  "AccountMask": "0000"
}

PaymentRequestId: The unique identifier for the payment.
RegistrationId: The registration ID for the user.
Amount: The charged amount (in cents).
Currency: The currency used in the transaction.
Status: The current status of the payment. See below for more details.
Timestamp: The date and time when the transaction was processed.
AccountMask: Last four digits of the user’s account, if the user is registered and has a linked account.

This webhook enables you to update your records and trigger any subsequent business processes.

Payment Statuses

Pending: The initial state of a payment request, awaiting further action or processing.
In Review: Triggered when a payment is flagged for safety or internal rule violations; it requires manual investigation.
Scheduled: The payment is set to be processed automatically on a specific future DueDate.
Card Payment Pending: The payer has initiated a card payment but has not yet completed the checkout form. See card payments for details.
Paid: The final successful state; occurs after a payment is accepted by the user (or automatically on a scheduled date).
Canceled: The payment was manually stopped by a back-office user.
Denied: The payment was rejected by a back-office user, typically following a review.

Status Transition Table

From State	Allowed To Move To…
Pending / Scheduled	Paid, Canceled, In Review, Denied, Card Payment Pending
Card Payment Pending	Paid, Canceled, Pending
In Review	Paid, Canceled, Denied
Paid / Canceled / Denied	None (Final States)

Get Started

Authorization

Companies

Users

Payments

Reporting

Webhooks

Demo Videos

Changelog

Creating a Payment Request

Overview

How It Works

Creating the Payment Request

Endpoint

Header Parameters

Request Body

Example Request

Response

Payment Confirmation

Payment Statuses

Status Transition Table

​Overview

​How It Works

​Creating the Payment Request

​Endpoint

​Header Parameters

​Request Body

​Example Request

​Response

​Payment Confirmation

​Payment Statuses

​Status Transition Table

Overview

How It Works

Creating the Payment Request

Endpoint

Header Parameters

Request Body

Example Request

Response

Payment Confirmation

Payment Statuses

Status Transition Table