Payment API Reference

This API reference provides information on available endpoints for fetching payments and payment methods.

The Payment model

Payments serve as transactions between businesses and customers, allowing the settlement of invoices. Customers have the option to make payments for invoices, while businesses can send payment receipts upon successful transactions. This process streamlines financial interactions, ensuring a clear record of completed transactions.

Properties

Name
id
Type
string
Field Type
Description
Unique identifier for the payment.
Name
payment_number
Type
string
Field Type
Description
The payment number.
Name
payment_date
Type
timestamp
Field Type
Description
The date of the payment.
Name
notes
Type
string
Field Type
Description
The notes of the payment.
Name
amount
Type
integer
Field Type
Description
The amount of the payment.
Name
invoice_id
Type
string
Field Type
Description
The ID of the invoice.
Name
status
Type
enum
Field Type
Description
The status of the payment.
Must be one of PAID, FAILED, or PROCESSING.
Name
vendor_business_id
Type
string
Field Type
Description
The ID of the vendor business.
Name
payment_method_id
Type
string
Field Type
Description
The ID of the payment method.
Name
customer_business_id
Type
string
Field Type
Description
The ID of the customer business.
Name
provider_intent_id
Type
string
Field Type
Description
The ID of the provider intent.
Name
sequence_number
Type
integer
Field Type
Description
The sequence number of the payment.
Name
payment_pdf_url
Type
string
Field Type
Description
The URL of the payment PDF.
Name
attachments
Type
array
Field Type
Description
The attachments of the payment.
Name
customer
Type
object
Field Type
Description
The customer of the payment.
Name
vendor
Type
object
Field Type
Description
The vendor of the payment.
Name
invoice
Type
object
Field Type
Description
The invoice of the payment.
Name
payment_method
Type
object
Field Type
Description
The payment method of the payment.
Name
payment_type
Type
string
Field Type
Description
The type of the payment.
Name
created_at
Type
timestamp
Field Type
Description
The creation date of the payment.

POSTapi/v1/payments/{id}/send-email

Send payment receipt

This endpoint allows you to mail the payment receipt to the corresponding customer's email address.

URL Parameters

Name
id
Type
string
Field Type
required
Description
The ID of the payment.

Body Parameters

Name
subject
Type
string
Field Type
required
Description
Subject of the email.
Name
body
Type
string
Field Type
required
Description
Body of the email.
Name
reply_to
Type
string
Field Type
required
Description
Reply to email address.
Name
to
Type
string
Field Type
required
Description
Email address of the recipient.

Request

POST

api/v1/payments/{id}/send-email

curl --request POST \
  "https://payments.your-domain.com/api/v1/payments/99783bf4-c49a-45d3-abc6-118ad6c80f34/send-email" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \
  --data "{
    \"subject\": \"You have received new payment receipt by {VENDOR_BUSINESS_NAME}\",
    \"body\": \"<p>Thank you for the payment.</p><p>Please view your payment receipt using the button below:</p>.\",
    \"reply_to\": \"business_email@example.com\",
    \"to\": \"customer_email@example.com\"
  }"

Response

{
  "data": {
    "id": "99783bf4-c49a-45d3-abc6-118ad6c80f34",
    "payment_number": "PAY-000001",
    "payment_date": 514339200,
    "notes": "Assumenda quo reprehenderit ipsum ullam.",
    "amount": 100,
    "status": "PAID",
    "invoice_id": "9aae0110-a4d6-4552-99de-4b4d3e3432f8",
    "vendor_business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
    "payment_method_id": "99783bf4-b652-4e06-a0a2-32d1eb1018c9",
    "customer_business_id": "98ed68ce-6964-4c2a-9430-8a849e373c52",
    "provider_intent_id": "pi_3OZCFRHphok22dPx1bVVta5fr",
    "payment_intent_id": "9b771b27-f935-4a2f-99aa-7a56e7cc437e",
    "sequence_number": 1,
    "payment_pdf_url": "https://payments.your-domain.com/payments/pdf/99783bf4-c49a-45d3-abc6-118ad6c80f34",
    "attachments": [],
    "customer": {},
    "payment_method": {
      "id": "99783bf4-b652-4e06-a0a2-32d1eb1018c9",
      "name": "Credit Card",
      "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
      "type": "GENERAL"
    },
    "total_processing_fee": 33,
    "created_at": 1687416810
  }
}

GETapi/v1/payments

List all payments

This endpoint returns a list of your payments.

Query Parameters

Name
limit
Type
integer
Field Type
optional
Description
A limit on the number of payments to be returned. (default is 10)
Name
page
Type
integer
Field Type
optional
Description
Page number for pagination. (default is 1)
Name
payment_number
Type
string
Field Type
optional
Description
Filter records by payment_number.
Name
type
Type
string
Field Type
optional
Description
1. incoming: Fetch payments where the current business is the customer.
2. outgoing: Fetch payments where the current business is the vendor.
3. All Payments (if type is not provided): Fetch all payments involving the current business as either a vendor or customer. If the business can act as both, include both types of payments. If the business is only a customer, fetch customer payments. If the business is only a vendor, fetch vendor payments.
Name
customer_business_id
Type
string
Field Type
optional
Description
Filter by customer_business_id (Only fetch payments of a given customer of this business)
Name
payment_method_id
Type
string
Field Type
optional
Description
Filter records by payment_method_id.

Request

GET

api/v1/payments

curl --request GET \
  --get "https://payments.your-domain.com/api/v1/payments" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \

Response

{
  "data": [
    {
      "id": "99783bf4-c49a-45d3-abc6-118ad6c80f34",
      "payment_number": "PAY-000001",
      "payment_date": 514339200,
      "notes": "Assumenda quo reprehenderit ipsum ullam.",
      "amount": 100,
      "status": "PAID",
      "invoice_id": "9aae0110-a4d6-4552-99de-4b4d3e3432f8",
      "vendor_business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
      "payment_method_id": "99783bf4-b652-4e06-a0a2-32d1eb1018c9",
      "customer_business_id": "98ed68ce-6964-4c2a-9430-8a849e373c52",
      "provider_intent_id": "pi_3OZCFRHphok22dPx1bVVta5fr",
      "payment_intent_id": "9b771b27-f935-4a2f-99aa-7a56e7cc437e",
      "sequence_number": 1,
      "payment_pdf_url": "https://payments.your-domain.com/payments/pdf/99783bf4-c49a-45d3-abc6-118ad6c80f34",
      "attachments": [],
      "customer": {},
      "invoice": {},
      "payment_method": {
        "id": "99783bf4-b652-4e06-a0a2-32d1eb1018c9",
        "name": "Credit Card",
        "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
        "type": "GENERAL"
      },
      "total_processing_fee": 33,
      "created_at": 1687416810
    }, {...}
  ]
}

GETapi/v1/payments/{id}

Retrieve a payment

This endpoint allows you to retrieve a Payment object.

URL Parameters

Name
id
Type
string
Field Type
required
Description
The ID of the payment.

Request

GET

api/v1/payments/{id}

curl --request GET \
  --get "https://payments.your-domain.com/api/v1/payments/99783bf4-c49a-45d3-abc6-118ad6c80f34" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \

Response

{
  "data": {
    "id": "99783bf4-c49a-45d3-abc6-118ad6c80f34",
    "payment_number": "PAY-000001",
    "payment_date": 514339200,
    "notes": "Assumenda quo reprehenderit ipsum ullam.",
    "amount": 100,
    "status": "PAID",
    "invoice_id": "9aae0110-a4d6-4552-99de-4b4d3e3432f8",
    "vendor_business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
    "payment_method_id": "99783bf4-b652-4e06-a0a2-32d1eb1018c9",
    "customer_business_id": "98ed68ce-6964-4c2a-9430-8a849e373c52",
    "provider_intent_id": "pi_3OZCFRHphok22dPx1bVVta5fr",
    "payment_intent_id": "9b771b27-f935-4a2f-99aa-7a56e7cc437e",
    "sequence_number": 1,
    "payment_pdf_url": "https://payments.your-domain.com/payments/pdf/99783bf4-c49a-45d3-abc6-118ad6c80f34",
    "attachments": [],
    "customer": {},
    "invoice": {},
    "payment_method": {
      "id": "99783bf4-b652-4e06-a0a2-32d1eb1018c9",
      "name": "Credit Card",
      "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
      "type": "GENERAL"
    },
    "vendor": {},
    "total_processing_fee": 33,
    "created_at": 1687416810
  }
}