Create Session

Creates a checkout session for one buyer account and one or more invoices and/or statements.

Swagger documentation:
https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=BTPay%20ExtendPay%20Service%20v1

Endpoint: POST https://arc-aegis.billtrust.com/btpay-extendpay/v1/tenants/{tenantId}/sessions

On success you receive:

Field	Description
extendPaySessionId	Id for Get/List and webhook correlation
paymentUrl	URL to open for the buyer
sessionExpiration	When paymentUrl stops working

Path parameters

Parameter	Description
tenantId	Your Billtrust tenant id (path only — do not send in the body)

Request body

Field	Type	Required	Description
accountNumber	string	Yes	Buyer account number in your system. Max 50 characters. Must not be -1. Must not contain :.
user	object	Yes	User for this session
user.email	string	Yes	Valid email address
user.firstName	string	No	First name
user.lastName	string	No	Last name
onCompleteUrl	string	Yes	Absolute https URL where the buyer returns after checkout
sourceType	string	Yes	supplierPortal, counterSoftware, fieldServiceApp, or buyerPortal
invoices	object	Conditional	Invoice collection
invoices.items	array	Conditional	Invoice items
statements	object	Conditional	Statement collection
statements.items	array	Conditional	Statement items

Include at least 1 and at most 250 items across invoices and statements combined.

Source types

sourceType is required and case-sensitive. Use the value that matches how the payment is being initiated:

Value	Description
supplierPortal	An internal user at your company logged into your portal making a payment on behalf of a customer
counterSoftware	An internal user at your company accepting payment from a customer physically at a retail location
fieldServiceApp	An internal user at your company accepting payment from a customer physically out in the field
buyerPortal	An external buyer user logged in to your system making a payment

Invoice item (invoices.items[])

Field	Type	Required	Description
invoiceNumber	string	Yes	Invoice number (unique within the request)
totalDue	string	Yes	Amount as a plain decimal string, greater than zero, at most 2 decimal places (example: "150.00"). No $ or commas.
dueDate	string	Yes	Date (yyyy-MM-dd)
billDate	string	No	Date (yyyy-MM-dd)
branchName	string	Yes	Branch for this document
ffdId	integer	No	Payment policy (FFD) id (positive)
ffdName	string	No	Payment policy (FFD) name
discountAmount	string	No	Must be sent with discountDate (both or neither). Same format as totalDue.
discountDate	string	No	Must be sent with discountAmount (yyyy-MM-dd).

Statement item (statements.items[])

Field	Type	Required	Description
totalDue	string	Yes	Amount as a plain decimal string, greater than zero, at most 2 decimal places
dueDate	string	Yes	Date (yyyy-MM-dd)
billDate	string	Yes	Date (yyyy-MM-dd)
branchName	string	Yes	Branch for this document
ffdId	integer	No	Payment policy (FFD) id (positive)
ffdName	string	No	Payment policy (FFD) name
discountAmount	string	No	Paired with discountDate
discountDate	string	No	Paired with discountAmount (yyyy-MM-dd)

Request notes

• Send amounts and dates as strings.
• Dates use ISO 8601 calendar form yyyy-MM-dd (for example "2026-09-15") — not date-time values with a time or timezone.
• Payments are always in the supplier default currency configured for your tenant. Completed transactions report that currency in currencyCode.
• Payment policy (FFD): omit both ffdId and ffdName to use the supplier default FFD; send either field when a document should use a specific policy instead of the default.

Example request

curl -X POST 'https://arc-aegis.billtrust.com/btpay-extendpay/v1/tenants/{tenantId}/sessions' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountNumber": "ACCT-100",
    "user": {
      "email": "buyer@example.com",
      "firstName": "Ada",
      "lastName": "Lovelace"
    },
    "onCompleteUrl": "https://supplier.example/return",
    "sourceType": "supplierPortal",
    "invoices": {
      "items": [
        {
          "invoiceNumber": "INV-100",
          "totalDue": "100.00",
          "dueDate": "2026-09-15",
          "billDate": "2026-08-01",
          "branchName": "MAIN"
        }
      ]
    },
    "statements": {
      "items": [
        {
          "totalDue": "75.00",
          "dueDate": "2026-09-20",
          "billDate": "2026-08-05",
          "branchName": "MAIN",
          "discountAmount": "5.00",
          "discountDate": "2026-08-20"
        }
      ]
    }
  }'

Example response — 200

{
  "extendPaySessionId": "c0ffee00-0000-4000-8000-000000000001",
  "paymentUrl": "https://checkout.example.billtrust.com/pay?token=eyJhbGciOi...",
  "sessionExpiration": "2026-08-11T15:30:00Z"
}

Notes

• One buyer account per request. Use a separate session for each account.
• If the buyer account does not yet exist in Billtrust, ExtendPay creates it from the account number you send.
• Open paymentUrl before sessionExpiration. If it expires, create a new session.
• Webhooks use your tenant webhook configuration (set by an administrator), not a URL on this request. See Webhooks.
• A 200 means checkout is ready (Open). Confirm payment later with Get session or a webhook (Complete).

Errors

When create hits a validation or setup problem, Billtrust returns an error immediately. You do not receive paymentUrl. The session is left in Failed status (it is not usable for checkout). Correct the request and call create again.

Failed creates use the standard error body (see Errors).

HTTP status	Typical cause
400	Request validation failed, invalid payment policy, or tenant not configured for ExtendPay
403	User is not allowed to perform this action
404	Tenant or user could not be found
409	Conflicting data (for example an inactive buyer account)
415	Send Content-Type: application/json
424	Tenant is not configured for checkout and/or ExtendPay
500	Unexpected error — contact support with correlationId
504	Request timed out — retry; contact support if it continues

After a successful create

1. Store extendPaySessionId with your payment attempt.
2. Send the buyer to paymentUrl.
3. When they return to onCompleteUrl, call Get session and/or wait for the webhook.
4. Treat payment as successful only when status is Complete.