Payment Sessions

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.

Create a customer

curl https://api.yorlet.com/v1/customers \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
        "email": "[email protected]"
      }'

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

Customer object

{
  "id": "cus_lrhplff1u4ZhIPSU",
  "object": "customer",
  "email": "[email protected]"
  // ... other fields on the Customer object
}

Create a Payment Session

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

Create a Payment Session

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.

Payment Session object

{
  "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-eyJhbGciOiJIUzI1NiJ9"
  // ... 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

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.

Send email to customer

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

Payment Session with reporting type

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

Transaction data

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

Payment Session with transaction data

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 to check its status and see the associated transaction.

Retrieve a Payment Session

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.

Completed Payment Session

{
  "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 if it is no longer needed.

Cancel a Payment Session

curl -X POST https://api.yorlet.com/v1/payment_sessions/{{PAYMENT_SESSION_ID}}/cancel \
  -H "Authorization: Bearer {{API_KEY}}"

Developer tools

Essentials

Integrations

Platforms

Create a customer

Create a Payment Session

Supported payment method types

Optional parameters

Reporting type

Transaction data

Retrieve a Payment Session

Cancel a Payment Session

​Create a customer

​Create a Payment Session

​Supported payment method types

​Share the Payment Session URL

​Optional parameters

​Reporting type

​Transaction data

​Retrieve a Payment Session

​Cancel a Payment Session

Create a customer

Create a Payment Session

Supported payment method types

Share the Payment Session URL

Optional parameters

Reporting type

Transaction data

Retrieve a Payment Session

Cancel a Payment Session