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

# Card payments

> Register external card transactions.

<Warning>
  Currently being updated for new endpoint logic
</Warning>

## Overview

If you process card payments through a terminal, POS system, or other external provider, you can register those transactions in SynchPay using the `/cardpayment` endpoint to keep all payment activity visible in one place.

### How it works

<Steps>
  <Step title="Obtain an access token">
    Authenticate by making a `POST` request to `/auth/token` with your `ClientId` and `ClientSecret`.
  </Step>

  <Step title="Register the card payment">
    Send a `POST` request to `/cardpayment` with the transaction details — amount, card type, transaction status, merchant identifier, and the payer's mobile number.
  </Step>

  <Step title="Payer receives notification">
    SynchPay sends the payer an SMS (and email, if provided) confirming the card payment was recorded.
  </Step>
</Steps>

### Endpoint

* **URL**: `https://api.synchpay.com/cardpayment`
* **Method**: `POST`
* **Authorization**: `Bearer <AccessToken>`

### Request body

| Parameter                | Type    | Description                                                                                                    | Required |
| ------------------------ | ------- | -------------------------------------------------------------------------------------------------------------- | -------- |
| `Amount`                 | integer | The payment amount in cents. For example, \$50.00 should be provided as `5000`.                                | Yes      |
| `MobileNumber`           | string  | The payer's phone number in international format (e.g., `+12025551234`).                                       | Yes      |
| `CardType`               | string  | The type of card used for the payment (e.g., `Visa`, `Mastercard`, `Amex`).                                    | Yes      |
| `TransactionStatus`      | string  | The status of the card transaction. Allowed values: `Pending`, `Succeeded`, `Failed`, `Cancelled`, `Refunded`. | Yes      |
| `MerchantId`             | string  | The identifier for the merchant associated with this card payment.                                             | Yes      |
| `Email`                  | string  | The payer's email address. If provided, SynchPay sends an email notification in addition to SMS.               | No       |
| `PatientReferenceNumber` | string  | An optional reference number for the payer in your system (e.g., a patient ID).                                | No       |

### Transaction statuses

| Status      | Description                                         |
| ----------- | --------------------------------------------------- |
| `Pending`   | The card transaction is still being processed.      |
| `Succeeded` | The payment was completed successfully.             |
| `Failed`    | The payment failed (e.g., declined card).           |
| `Cancelled` | The payment was cancelled before completion.        |
| `Refunded`  | The payment was refunded after a successful charge. |

### Example request

```json theme={null}
{
  "Amount": 7500,
  "MobileNumber": "+12025551234",
  "CardType": "Visa",
  "TransactionStatus": "Succeeded",
  "MerchantId": "merchant-001",
  "Email": "payer@example.com",
  "PatientReferenceNumber": "PAT-10042"
}
```

### Response

A successful request returns `200 OK` with no response body.

### Error responses

| Status code | Cause                                                                   |
| ----------- | ----------------------------------------------------------------------- |
| `400`       | Validation failed (e.g., missing required field, invalid status).       |
| `401`       | Missing or invalid access token.                                        |
| `422`       | Business rule violation (e.g., company not found for given identifier). |

### When to use this endpoint

Use the `/cardpayment` endpoint when you want to:

* **Consolidate reporting** — See card and account-to-account payments in one place.
* **Enable payer notifications** — Let payers receive SMS or email confirmations for card payments processed outside SynchPay.
* **Track card transactions** — Keep a record of external card payments alongside your SynchPay payment activity.

<Info>
  This endpoint records card transactions that were processed by an external provider. It does not process card payments directly. To collect a payment through SynchPay, use the [payment request](/synchpay/make-payment) endpoint instead.
</Info>