​
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

​
Request Body

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

ParameterTypeDescriptionRequired
RegistrationIdstringThe unique identifier for the user registration, obtained from the /user/register endpoint IMPORTANT: it is required if ContactNumberwas omittedNo *
ContactNumberstringInternational format (eg +1 for US). IMPORTANT: it is required if RegistrationId was omittedNo *
EmailAddressstringE-mail address for notificationsNo
CompanyIdstringThe unique identifier for the company requesting the payment. When missing default one will be used from integrationNo
AmountintegerThe payment amount expressed in cents. For example, $50.00 should be provided as 5000Yes
ShortDescriptionstringA brief description of the service or product for which payment is being requestedNo
FeePayerstringSpecifies who will cover the transaction fee. Acceptable values: "client", "partner", or "ask" . Value"ask"means that client can choose while acceptingYes
ReferencestringReference with external system eg. payment IDNo
AttachmentstringPDF file in base64 formatNo
DueDatestringDue date in date only format eg “2023-05-30”. If ommited the next day will be appliedNo
EnableAutoPayboolAsks user for auto pay consentNo
AutoPayLimitintegerAuto pay limit in cents. For example, $50.00 should be provided as 5000No
MetadataobjectFlat 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.