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

# Payment Sessions

> Learn how to create and manage Payment Sessions to accept a payment.

export const APIBadge = () => {
  return <div style={{
    display: 'inline-block',
    backgroundColor: 'rgb(var(--primary-light))',
    color: '#ffffff',
    padding: '1px 4px',
    borderRadius: '.375rem',
    borderColor: 'rgb(var(--gray-200))',
    borderWidth: '1px',
    position: 'relative',
    top: '-2px',
    marginLeft: '4px',
    fontSize: '11px',
    fontWeight: 700,
    letterSpacing: '0.05em',
    lineHeight: '11px'
  }}>
      API
    </div>;
};

Payment Sessions are a way to accept one-time payments from your customers. You can create a Payment Session for a specific amount and currency, and share the Payment Session URL with your customers. Your customers can then pay using their preferred payment method.

## Create a customer

Before creating a Payment Session, you need a customer to associate the payment with. You can either use an existing customer or create a new one using the [Customers API<APIBadge />](https://docs.yorlet.com/api/customers/create-a-customer).

```bash Create a customer theme={"theme":"dracula"}
curl https://api.yorlet.com/v1/customers \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
        "email": "jane@example.com"
      }'
```

If the request completed successfully, the response contains the customer object.

```json Customer object theme={"theme":"dracula"}
{
  "id": "cus_lrhplff1u4ZhIPSU",
  "object": "customer",
  "email": "jane@example.com"
  // ... other fields on the Customer object
}
```

## Create a Payment Session

To [create a Payment Session<APIBadge />](https://docs.yorlet.com/api/payment-sessions/create-a-payment-session), you need to specify the `amount`, `currency`, `customer`, `mode`, and `payment_method_types`. You can optionally include a `return_url` to redirect customers after the payment is completed.

```bash Create a Payment Session theme={"theme":"dracula"}
curl https://api.yorlet.com/v1/payment_sessions \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
        "amount": 10000,
        "currency": "gbp",
        "customer": "{{CUSTOMER_ID}}",
        "mode": "payment",
        "payment_method_types": ["card"],
        "return_url": "https://example.com/success"
      }'
```

If the request completed successfully, the Payment Session object contains the `url` parameter.

```json Payment Session object theme={"theme":"dracula"}
{
  "id": "py_sess_lvu4xju9NAB38beQ",
  "object": "payment_session",
  "amount": 10000,
  "currency": "gbp",
  "customer": "cus_lrhplff1u4ZhIPSU",
  "status": "unpaid",
  "url": "https://pay.yorlet.com/sessions/py_sess_lvu4xju9NAB38beQ"
  // ... other fields on the Payment Session object
}
```

### Supported payment method types

You can accept payments using the following payment method types:

| Type                  | Description                |
| --------------------- | -------------------------- |
| `card`                | Credit or debit card       |
| `bacs_debit`          | Bacs Direct Debit (UK)     |
| `sepa_debit`          | SEPA Direct Debit (EU)     |
| `autogiro`            | Autogiro (Sweden)          |
| `bank_transfer`       | Bank transfer              |
| `direct_transfer`     | Direct transfer            |
| `gbp_credit_transfer` | GBP credit transfer        |
| `pay_by_bank`         | Pay by Bank (Open Banking) |
| `card_present`        | In-person card payment     |

### Share the Payment Session URL

After creating a Payment Session, share the `url` with your customer. They will be guided through a secure flow to complete the payment. Once complete, they will be redirected to your `return_url`.

You can also set `send_email` to `true` to automatically send the URL to the customer's email address.

```bash Send email to customer theme={"theme":"dracula"}
curl https://api.yorlet.com/v1/payment_sessions \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
        "amount": 10000,
        "currency": "gbp",
        "customer": "{{CUSTOMER_ID}}",
        "mode": "payment",
        "payment_method_types": ["card"],
        "send_email": true
      }'
```

## Optional parameters

### Reporting type

Use the `reporting_type` parameter to categorize the payment for reporting purposes. Defaults to `charge`.

| Type           | Description              |
| -------------- | ------------------------ |
| `advance_rent` | Advance rent payment     |
| `charge`       | General charge (default) |
| `deposit`      | Deposit payment          |
| `holding_fee`  | Holding fee payment      |
| `rent`         | Rent payment             |

```bash Payment Session with reporting type theme={"theme":"dracula"}
curl https://api.yorlet.com/v1/payment_sessions \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
        "amount": 100000,
        "currency": "gbp",
        "customer": "{{CUSTOMER_ID}}",
        "mode": "payment",
        "payment_method_types": ["card", "bacs_debit"],
        "reporting_type": "deposit",
        "return_url": "https://example.com/success"
      }'
```

### Statement descriptor

Use the `statement_descriptor` parameter to set the text that appears on the customer's bank statement.

### Transaction data

Use the `transaction_data` parameter to configure how the resulting transaction should be processed, including transfer behavior and customer balance options.

```bash Payment Session with transaction data theme={"theme":"dracula"}
curl https://api.yorlet.com/v1/payment_sessions \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
        "amount": 100000,
        "currency": "gbp",
        "customer": "{{CUSTOMER_ID}}",
        "mode": "payment",
        "payment_method_types": ["card"],
        "transaction_data": {
          "unit": "{{UNIT_ID}}",
          "transfer_data": {
            "use_unit_ownership": true
          }
        },
        "return_url": "https://example.com/success"
      }'
```

| Parameter                          | Type    | Description                                                                       |
| ---------------------------------- | ------- | --------------------------------------------------------------------------------- |
| `unit`                             | string  | The ID of the unit associated with the transaction                                |
| `transfer_data.use_unit_ownership` | boolean | If a unit ID is supplied, transfers will be created based on the unit's ownership |
| `customer_balance.apply`           | boolean | Whether to apply the transaction amount to the customer's balance                 |
| `customer_balance.description`     | string  | A description of the transaction to be applied to the customer's balance          |

## Retrieve a Payment Session

You can [retrieve a Payment Session<APIBadge />](https://docs.yorlet.com/api/payment-sessions/retrieve-a-payment-session) to check its status and see the associated transaction.

```bash Retrieve a Payment Session theme={"theme":"dracula"}
curl https://api.yorlet.com/v1/payment_sessions/{{PAYMENT_SESSION_ID}} \
  -H "Authorization: Bearer {{API_KEY}}"
```

Once the customer completes the payment, the `status` field will change to `paid` and the `transaction` field will contain the ID of the created transaction.

```json Completed Payment Session theme={"theme":"dracula"}
{
  "id": "py_sess_lvu4xju9NAB38beQ",
  "object": "payment_session",
  "amount": 10000,
  "currency": "gbp",
  "customer": "cus_lrhplff1u4ZhIPSU",
  "status": "paid",
  "transaction": "txn_m2k4jf8sL9pQr3nT"
  // ... other fields on the Payment Session object
}
```

## Cancel a Payment Session

You can [cancel a Payment Session<APIBadge />](https://docs.yorlet.com/api/payment-sessions/cancel-a-payment-session) if it is no longer needed.

```bash Cancel a Payment Session theme={"theme":"dracula"}
curl -X POST https://api.yorlet.com/v1/payment_sessions/{{PAYMENT_SESSION_ID}}/cancel \
  -H "Authorization: Bearer {{API_KEY}}"
```