> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.synchpay.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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](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](/synchpay/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.

<Note>
  `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](/synchpay/payment-debit-auth) for more details on how debit auth works.
</Note>

### Example Request

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](/synchpay/card-payment) 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)*                                   |