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
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
EnableAutoPay	bool	Asks user for auto pay consent	No
AutoPayLimit	integer	Auto pay limit in cents. For example, $50.00 should be provided as 5000	No
Metadata	object	Flat object with metadata. Example: { "additionalProp1": "foo", "additionalProp2": "bar" }	No

* Either RegistrationId or ContactNumber have to be specified.

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

Response

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

{
  "PaymentRequestId": "ce0e3549-a83e-4cf6-bb5c-1d50a21d8af7",
}

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

• 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 (e.g., “Processing” or “Completed”).
• Timestamp: The date and time when the transaction was processed.

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