Creating a Payment Request

Follow these steps to request money from a registered user using the SynchPay API.

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

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

2. Submit a Payment Request

   With the access token, you can send a JSON payload to the /payment/create endpoint. This payload must include essential details such as the user’s registration identifier, the company identifier, the payment amount (in cents), a brief description, and the fee payer.

3. Processing the Request

   Once the payment request is submitted, the consumer receives a prompt—via their registered bank account or through the SynchPay app—to approve the transaction.

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

Request Body

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

Parameter	Type	Description	Required
RegistrationId	string	The unique identifier for the user registration, obtained from the /user/register endpoint IMPORTANT: it is required if ContactNumberwas omitted	No *
ContactNumber	string	International format (eg +1 for US). IMPORTANT: it is required if RegistrationId was omitted	No *
EmailAddress	string	E-mail address for notifications	No
CompanyId	string	The unique identifier for the company requesting the payment. When missing default one will be used from integration	No
CompanyReferenceId	string	An alternative company identifier from your system. Use this instead of CompanyId to look up the company by your own reference	No
Amount	integer	The payment amount expressed in cents. For example, $50.00 should be provided as 5000	Yes
ShortDescription	string	A brief description of the service or product for which payment is being requested	No
FeePayer	string	Specifies who will cover the transaction fee. Acceptable values: "client", "partner", or "ask" . Value"ask"means that client can choose while accepting	Yes
Reference	string	Reference with external system eg. payment ID	No
Attachment	string	PDF file in base64 format	No
DueDate	string	Due date in date only format eg “2023-05-30”. If ommited the next day will be applied	No
EnableDebitAuth	bool	Sends a debit authorization request to the user. Functions the same as EnableAutoPay	No
DebitAuthLimit	integer	Debit authorization limit in cents. For example, $50.00 should be provided as 5000. Functions the same as AutoPayLimit	No
EnableAutoPay	bool	Asks user for auto pay consent. Alias for EnableDebitAuth	No
AutoPayLimit	integer	Auto pay limit in cents. For example, $50.00 should be provided as 5000. Alias for DebitAuthLimit	No
Metadata	object	Flat object with metadata. Example: { "additionalProp1": "foo", "additionalProp2": "bar" }	No

* Either RegistrationId or ContactNumber have to be specified.

You can identify the company using either CompanyId (the SynchPay identifier) or CompanyReferenceId (your own external reference). If both are provided, CompanyId takes precedence. If neither is provided, the default company from your integration is used.

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",
  "CompanyId": "0bba248e-2d4b-4666-bf04-dd3c65c8fc03",
  "Amount": 5000,
  "ShortDescription": "Additional services rendered.",
  "FeePayer": "client",
  "EnableAutoPay": true,
  "AutoPayLimit": 10000,
  "Metadata": {
    "additionalProp1": "foo",
    "additionalProp2": "bar"
  }
}

Alternatively, you can use CompanyReferenceId instead of CompanyId to identify the company by your own reference:

{
  "RegistrationId": "6e8d9257-bd5f-45cf-8f29-6d0ae8a6d991",
  "CompanyReferenceId": "your-internal-id-123",
  "Amount": 5000,
  "ShortDescription": "Additional services rendered.",
  "FeePayer": "client"
}

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

Payment Confirmation

After the consumer approves the payment request via their registered bank account 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.
• 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
In Review	Paid, Canceled, Denied
Paid / Canceled / Denied	None (Final States)