Payments

TalusPay API (v1)

The Talus Pay API is organized into two main areas: Merchant Onboarding and Payments. The Merchant Onboarding endpoints are designed to facilitate the registration, verification, and configuration of new merchants within the platform. This includes creating merchant accounts, submitting necessary documentation, and managing compliance checks.

On the other hand, the Payments endpoints focus on transaction processing, allowing merchants to accept payments, initiate refunds, and handle transaction statuses. This section is structured to manage payment methods, securely process card transactions, and retrieve transaction histories, ensuring a smooth flow of payment operations for merchants. Together, these two areas provide comprehensive support for managing both the setup and ongoing financial activities of merchants.

The TalusPay status page provides real-time updates on the operational status of API services, including onboarding and payments, as well as historical uptime data. You can check the current service status at Status page

Download OpenAPI description
openapi.json
openapi.yaml
Overview
URL

https://docs.taluspay.com

TalusPay

engineering@taluspay.com

Languages
Servers
Mock server

https://docs.taluspay.com/_mock/openapi/

Production environment onboarding

https://api.taluspay.com/

Sandbox environment onboarding

https://api.taluspay-sandbox.com/

Merchants

Operations

Onboarding Links

Operations

Webhooks

Operations

Statements

Operations

Payments

Operations

Create Terminal Payment

Request

Create a terminal payment

Bodyapplication/jsonrequired
terminal_idstringrequired

Unique identifier for the terminal

Example: "234h2ev0i4726hij9o00"
signature_requiredbooleanrequired

Flag to indicate if a signature is required

Example: false
merchant_idstringrequired

Unique identifier for the merchant

Example: "merchant_02c7h71rf3eg396idngupsr66t"
amountinteger(int32)required

Amount of the payment

Example: 100
tipinteger(int32)required

Tip amount

Example: 1
taxinteger(int32)required

Tax amount

Example: 10
debitbooleanrequired

Flag to indicate if terminal should allow debit cards

Example: true
isTaxValidbooleanrequired
curl -i -X POST \
  https://docs.taluspay.com/_mock/openapi/v1/terminal \
  -H 'Content-Type: application/json' \
  -d '{
    "terminal_id": "234h2ev0i4726hij9o00",
    "signature_required": false,
    "merchant_id": "merchant_02c7h71rf3eg396idngupsr66t",
    "amount": 100,
    "tip": 1,
    "tax": 10,
    "debit": true,
    "isTaxValid": true
  }'

Responses

Invoice payment created successfully

Bodyapplication/json
payment_typestringrequired

Type of payment

Enum"MANUAL""INVOICE""TERMINAL""SCAN_TO_PAY""CUSTOMER""REFUND"
idstringrequired

Unique identifier for the payment request

Example: "preq_01h455vb4pex5vsknk084sn02q"
payment_asset_urlstringrequired

URL of the payment asset

email_addressstringrequired

Email address of the customer

Example: "test@test.ai"
phone_numberstring

Phone number of the customer

amountinteger(int32)required

Amount of the payment

tipinteger(int32)required

Tip amount

taxinteger(int32)required

Tax amount

statusstringrequired

Status of the payment request

Response
application/json

Terminal Payment

{
  "payment_type": "TERMINAL",
  "id": "preq_01h455vb4pex5vsknk084sn02q",
  "email_address": "test@test.ai",
  "phone_number": "1234567890",
  "amount": 100,
  "tip": 20,
  "tax": 14340,
  "status": "CREATED"
}

Create Scan To Pay Payment

Request

Create a scan-to-pay payment

Bodyapplication/jsonrequired
merchant_idstringrequired

Unique identifier for the merchant

Example: "merchant_02c7h71rf3eg396idngupsr66t"
tipinteger(int32)required

Tip amount

Example: 1
itemsArray of objects(ItemBody)required

List of items

items[].​namestringrequired

Name of the item

Example: "Door Lockout service"
items[].​quantityinteger(int32)required

Quantity of the item

Example: 1
items[].​unit_priceinteger(int32)required

Unit price of the item

Example: 47800
taxinteger(int32)required

Tax amount

Example: 10
amountinteger(int32)required

Amount of the payment. If items are provided, amount should not be specified.

Example: 100
isTaxValidbooleanrequired
taxPercentstringrequired
curl -i -X POST \
  https://docs.taluspay.com/_mock/openapi/v1/scan_to_pay \
  -H 'Content-Type: application/json' \
  -d '{
    "merchant_id": "merchant_02c7h71rf3eg396idngupsr66t",
    "tip": 20,
    "items": [
      {
        "name": "Item 1",
        "quantity": 1,
        "unit_price": 100
      }
    ],
    "tax": 14340
  }'

Responses

Invoice payment created successfully

Bodyapplication/json
payment_typestringrequired

Type of payment

Enum"MANUAL""INVOICE""TERMINAL""SCAN_TO_PAY""CUSTOMER""REFUND"
idstringrequired

Unique identifier for the payment request

Example: "preq_01h455vb4pex5vsknk084sn02q"
payment_asset_urlstringrequired

URL of the payment asset

email_addressstringrequired

Email address of the customer

Example: "test@test.ai"
phone_numberstring

Phone number of the customer

amountinteger(int32)required

Amount of the payment

tipinteger(int32)required

Tip amount

taxinteger(int32)required

Tax amount

statusstringrequired

Status of the payment request

Response
application/json

Scan To Pay Payment

{
  "payment_type": "SCAN_TO_PAY",
  "id": "preq_01h455vb4pex5vsknk084sn02q",
  "payment_asset_url": "https://url.com/invoice/71f34949-eef4-4dcc-a899-6038634760c3",
  "email_address": "test@test.ai",
  "phone_number": "1234567890",
  "amount": 100,
  "tip": 20,
  "tax": 14340,
  "status": "CREATED"
}

Create Manual Payment

Request

Create a manual payment

Bodyapplication/jsonrequired
tokenstringrequired

Payment token

Example: "16RgvZ9XBTz4IUEIM0mD31f3808okqN2"
merchant_idstringrequired

Unique identifier for the merchant

Example: "merchant_02c7h71rf3eg396idngupsr66t"
amountinteger(int32)required

Payment amount

Example: 100
tipinteger(int32)required

Tip amount

Example: 1
taxinteger(int32)required

Tax amount

Example: 10
isTaxValidbooleanrequired
curl -i -X POST \
  https://docs.taluspay.com/_mock/openapi/v1/manual \
  -H 'Content-Type: application/json' \
  -d '{
    "token": "16RgvZ9XBTz4IUEIM0mD31f3808okqN2",
    "merchant_id": "merchant_02c7h71rf3eg396idngupsr66t",
    "amount": 100,
    "tip": 1,
    "tax": 10,
    "isTaxValid": true
  }'

Responses

Manual payment created successfully

Bodyapplication/json
idstring

Unique identifier for the charge

Example: "ch_01j8emz8chfxbb2bqmtref8ch7"
merchantobject(Merchant)required
merchant.​idstringrequired

Unique identifier for the merchant

Example: "merchant_02c7h71rf3eg396idngupsr66t"
payment_typestringrequired

Type of payment for the charge

Example: "MANUAL"
statusstringrequired

status of the charge

Enum"AUTHORIZED""SETTLED"
Example: "SETTLED"
requested_amountinteger(int32)required

Requested amount for the charge

Example: 100
amount_authorizedinteger(int32)required

Amount authorized for the charge

Example: 100
amount_capturedinteger(int32)required

Amount captured for the charge

Example: 100
tipinteger(int32)required

Tip amount for the charge

Example: 1
taxinteger(int32)required

Tax amount for the charge

Example: 10
card_last_4string

Last 4 digits of the card used for the charge

Example: "1234"
card_brandstring

Brand of the card used for the charge

Example: "VISA"
created_atinteger(int32)required

Timestamp when the charge was created

Example: 1727875117482
card_entry_methodstringrequired

Method used for card entry

Enum"SWIPE""CHIP""MANUAL"
Example: "MANUAL"
billing_addressobject(PaymentBillingAddress)

Billing address details

card_expiration_datestring

Expiration date of the card

Example: "01/27"
card_typestring

Type of the card

Example: "debit"
failure_reasonstring

Reason for the charge failure

Example: "Card declined"
Response
application/json
{
  "id": "ch_01j8emz8chfxbb2bqmtref8ch7",
  "merchant": {
    "id": "merchant_02c7h71rf3eg396idngupsr66t"
  },
  "payment_type": "MANUAL",
  "status": "SETTLED",
  "requested_amount": 100,
  "amount_authorized": 100,
  "amount_captured": 100,
  "tip": 1,
  "tax": 10,
  "card_last_4": "1234",
  "card_brand": "VISA",
  "created_at": 1727875117482,
  "card_entry_method": "MANUAL",
  "billing_address": {
    "company": "Acme Corp",
    "phone": "+1234567890",
    "email": "example@domain.com",
    "first_name": "John",
    "last_name": "Doe",
    "address_line_1": "123 Main St",
    "address_line_2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "postal_code": "10001",
    "country": "USA",
    "fax": "+1234567890"
  },
  "card_expiration_date": "01/27",
  "card_type": "debit",
  "failure_reason": "Card declined"
}

Create Invoice Payment

Request

Create an invoice payment

Bodyapplication/jsonrequired
merchant_idstringrequired

Unique identifier for the merchant

Example: "merchant_02c7h71rf3eg396idngupsr66t"
email_addressstringrequired

Email address of the customer

Example: "test@test.com"
send_smsbooleanrequired

Send invoice to the customer using SMS

Example: true
send_emailbooleanrequired

Send invoice to the customer using email

Example: true
phone_numberstring

Phone number of the customer

Example: "4695809533"
tipinteger(int32)required

Tip amount

Example: 20
itemsArray of objects(ItemBody)required

List of items

items[].​namestringrequired

Name of the item

Example: "Door Lockout service"
items[].​quantityinteger(int32)required

Quantity of the item

Example: 1
items[].​unit_priceinteger(int32)required

Unit price of the item

Example: 47800
taxinteger(int32)required

Tax amount

Example: 10
amountinteger(int32)required

Amount of the payment. If items are provided, amount should not be specified.

Example: 100
sendViastringrequired
Enum"none""text""email""both"
isTaxValidbooleanrequired
taxPercentstringrequired
curl -i -X POST \
  https://docs.taluspay.com/_mock/openapi/v1/invoice \
  -H 'Content-Type: application/json' \
  -d '{
    "merchant_id": "merchant_02c7h71rf3eg396idngupsr66t",
    "tip": 20,
    "items": [
      {
        "name": "Item 1",
        "quantity": 1,
        "unit_price": 100
      }
    ],
    "tax": 14340
  }'

Responses

Invoice payment created successfully

Bodyapplication/json
payment_typestringrequired

Type of payment

Enum"MANUAL""INVOICE""TERMINAL""SCAN_TO_PAY""CUSTOMER""REFUND"
idstringrequired

Unique identifier for the payment request

Example: "preq_01h455vb4pex5vsknk084sn02q"
payment_asset_urlstringrequired

URL of the payment asset

email_addressstringrequired

Email address of the customer

Example: "test@test.ai"
phone_numberstring

Phone number of the customer

amountinteger(int32)required

Amount of the payment

tipinteger(int32)required

Tip amount

taxinteger(int32)required

Tax amount

statusstringrequired

Status of the payment request

Response
application/json

Invoice Payment

{
  "payment_type": "INVOICE",
  "id": "preq_01h455vb4pex5vsknk084sn02q",
  "payment_asset_url": "https://url.com/invoice/71f34949-eef4-4dcc-a899-6038634760c3",
  "email_address": "test@test.ai",
  "phone_number": "1234567890",
  "amount": 100,
  "tip": 20,
  "tax": 14340,
  "status": "CREATED"
}

Create Customer Payment

Request

Create a customer payment

Bodyapplication/jsonrequired
customer_idstringrequired

Unique identifier for the customer

Example: "cust_02c7t70ef3ig396idugupsr99j"
merchant_idstringrequired

Unique identifier for the merchant

Example: "merchant_02c7h71rf3eg396idngupsr66t"
payment_method_idstringrequired

Unique identifier for the payment method

Example: "payment_method_04c7h77rf3ig386ilngopty49z"
amountinteger(int32)required

Amount of the payment

Example: 100
tipinteger(int32)required

Tip amount

Example: 1
taxinteger(int32)required

Tax amount

Example: 10
isTaxValidbooleanrequired
curl -i -X POST \
  https://docs.taluspay.com/_mock/openapi/v1/customer_charge \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_id": "cust_02c7t70ef3ig396idugupsr99j",
    "merchant_id": "merchant_02c7h71rf3eg396idngupsr66t",
    "payment_method_id": "payment_method_04c7h77rf3ig386ilngopty49z",
    "amount": 100,
    "tip": 1,
    "tax": 10,
    "isTaxValid": true
  }'

Responses

Customer payment created successfully

Bodyapplication/json
idstring

Unique identifier for the charge

Example: "ch_01j8emz8chfxbb2bqmtref8ch7"
merchantobject(Merchant)required
merchant.​idstringrequired

Unique identifier for the merchant

Example: "merchant_02c7h71rf3eg396idngupsr66t"
payment_typestringrequired

Type of payment for the charge

Example: "MANUAL"
statusstringrequired

status of the charge

Enum"AUTHORIZED""SETTLED"
Example: "SETTLED"
requested_amountinteger(int32)required

Requested amount for the charge

Example: 100
amount_authorizedinteger(int32)required

Amount authorized for the charge

Example: 100
amount_capturedinteger(int32)required

Amount captured for the charge

Example: 100
tipinteger(int32)required

Tip amount for the charge

Example: 1
taxinteger(int32)required

Tax amount for the charge

Example: 10
card_last_4string

Last 4 digits of the card used for the charge

Example: "1234"
card_brandstring

Brand of the card used for the charge

Example: "VISA"
created_atinteger(int32)required

Timestamp when the charge was created

Example: 1727875117482
card_entry_methodstringrequired

Method used for card entry

Enum"SWIPE""CHIP""MANUAL"
Example: "MANUAL"
billing_addressobject(PaymentBillingAddress)

Billing address details

card_expiration_datestring

Expiration date of the card

Example: "01/27"
card_typestring

Type of the card

Example: "debit"
failure_reasonstring

Reason for the charge failure

Example: "Card declined"
Response
application/json

Customer Payment

{
  "id": "ch_01j8emz8chfxbb2bqmtref8ch7",
  "merchant": {
    "id": "merchant_02c7h71rf3eg396idngupsr66t"
  },
  "payment_type": "CUSTOMER",
  "amount_authorized": 100,
  "amount_captured": 100,
  "requested_amount": 100,
  "tip": 1,
  "tax": 10,
  "card_last_4": "1234",
  "card_brand": "VISA",
  "created_at": 1727875117482,
  "card_entry_method": "MANUAL",
  "billing_address": {
    "company": "Acme Corp",
    "phone": "+1234567890",
    "email": "example@domain.com",
    "firstName": "John",
    "lastName": "Doe",
    "addressLine1": "123 Main St",
    "addressLine2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "postalCode": "10001",
    "country": "USA",
    "fax": "+1234567890"
  },
  "card_expiration_date": "01/27",
  "card_type": "debit",
  "status": "PENDING_SETTLEMENT"
}

Refunds

Operations

Charges

Operations