API Reference | Waivr Docs

Introduction

The Waivr API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Production:
https://app.waivr.co/api/waivr-app

Sandbox:
https://stage.waivr.co/

Customer

The Customer object represents a customer of your business. A customer is created when an individual subscribes to a product or service after providing name and email.

Create a customer

Headers

Accept string

required

Controls type of payload accepted by endpoint
Default: application/json

Authorization string

required

Authorization token that can be of two types: JWT or API
Default: <your key><your secret>

reqSessionId string

required

Request Session UUID to track call through logs
Default: 17e9461a-b609-463b-9a31-083aaa33db2c

Body

merchantUid string

required

Unique identifier for a merchant‍

email string

required

Customer's email‍

firstName string

required

Customer's first name‍

lastName string

required

Customer's last name‍

phoneNumber string

Customer's phone number‍

address string

Customer's address

POST /customers

curl --request post \
--url https://app.waivr.co/api/waivr-app/v1/customers \
--data @- <<EOF
{
"merchantUid": "f021c403-0dbd-4654-9153-2f918579834f",
"email": "john.snow@northwall.co",
"firstName": "John",
"lastName": "Snow",
"phoneNumber": "14444444444",
"address": {
"line1": "62 Blackwater Bay",
"line2": "",
"city": "King's Landing",
"state": "Seven Kingdom",
"country": "Westeros",
"zipCode": "29812"
}
}
EOF

curl --request post \ --url https://app.waivr.co/api/waivr-app/v1/customers \ --data @- <<EOF{ "merchantUid": "f021c403-0dbd-4654-9153-2f918579834f", "email": "john.snow@northwall.co", "firstName": "John", "lastName": "Snow", "phoneNumber": "14444444444", "address": { "line1": "62 Blackwater Bay", "line2": "", "city": "King's Landing", "state": "Seven Kingdom", "country": "Westeros", "zipCode": "29812" }}EOF

Sample Response

{
   "uid": "53db8c10-9f7b-4dde-bb3a-6a9faf190ff6",
   "createDate": "2022-12-12T19:57:44.438588476Z",
   "updateDate": "2022-12-12T19:57:44.623806274Z",
   "email": "john.snow@northwall.co",
   "firstName": "John",
   "lastName": "Snow",
   "phoneNumber": "14444444444",
   "address": {
       "line1": "62 Blackwater Bay",
       "line2": null,
       "city": "King's Landing",
       "state": "Seven Kingdom",
       "country": "Westeros",
       "zipCode": "29812"
   }
}

Bank Account

A bank account that a customer uses to make a payment. Waivr utilizes Plaid for bank connections.

Create a link for a bank connection

Headers

Accept string

required

Controls type of payload accepted by endpoint
Default: application/json

Authorization string

required

Authorization token that can be of two types: JWT or API
Default: <your key><your secret>

reqSessionId string

required

Request Session UUID to track call through logs
Default: b687e8ee-5d5a-49ec-9032-c8b9a292b6ef

Body

merchantUid string

required

Unique identifier for a merchant‍

redirectURL string

required

Redirect URL required for OAuth bank account connection. The URL must be on the same page or following page on the checkout flow hosted by your frontend

POST /connectaccounts/render

curl --request post \
--url https://app.waivr.co/api/waivr-app/v1/connectaccounts/render \
--data '
{
"merchantUid": "f021c403-0dbd-4654-9153-2f918579834f",
"redirectUrl": "https://winterfell.co/kingOfTheNorth"
}
'

curl --request post \ --url https://app.waivr.co/api/waivr-app/v1/connectaccounts/render \ --data '{ "merchantUid": "f021c403-0dbd-4654-9153-2f918579834f", "redirectUrl": "https://winterfell.co/kingOfTheNorth"}'

Connect a bank account

Headers

Accept string

required

Controls type of payload accepted by endpoint
Default: application/json

Authorization string

required

Authorization token that can be of two types: JWT or API
Default: <your key><your secret>

reqSessionId string

required

Request Session UUID to track call through logs
Default: b687e8ee-5d5a-49ec-9032-c8b9a292b6ef

Body

merchantUid string

required

Unique identifier for a merchant

customerUid string

required

Unique identifier for a customer

institution object

required

Plaid's bank institution model

publicToken string

required

External public token to link a Plaid's bank account

POST /connectaccounts/connect

curl --request post \
--url https://app.waivr.co/api/waivr-app/v1/connectaccounts/connect \
--data '
{
"merchantUid": "f021c403-0dbd-4654-9153-2f918579834f",
"customerUid": "53db8c10-9f7b-4dde-bb3a-6a9faf190ff6",
"institution": {
"accountIdentifier": "BA66MD4Q7KFgrm9lXJJPcbK1ZPkW1xcAMmeRW"
},
"publicToken": "public-sandbox-4aa91553-561e-4bd6-ac59-d9d8f643fdce"
}
'

curl --request post \ --url https://app.waivr.co/api/waivr-app/v1/connectaccounts/connect \ --data '{ "merchantUid": "f021c403-0dbd-4654-9153-2f918579834f", "customerUid": "53db8c10-9f7b-4dde-bb3a-6a9faf190ff6", "institution": { "accountIdentifier": "BA66MD4Q7KFgrm9lXJJPcbK1ZPkW1xcAMmeRW" }, "publicToken": "public-sandbox-4aa91553-561e-4bd6-ac59-d9d8f643fdce"}'

Sample Response

{
   "type": "PLAID",
   "linkingAccessToken": "link-sandbox-f152b8ad-01e6-445f-b085-a1cfa2c3977d",
   "validUntil": "2022-12-13T00:07:18Z",
   }
}

Payment Instruction

The payment instruction provides the payment frequency and billing date and defines when a payment will be initiated. A payment instruction is either Active when the customer’s subscription is active or Inactive when the customer’s subscription is canceled or suspended.

Create a payment instruction

Headers

Accept string

required

Controls type of payload accepted by endpoint
Default: application/json

Authorization string

required

Authorization token that can be of two types: JWT or API
Default: <your key><your secret>

reqSessionId string

required

Request Session UUID to track call through logs
Default: b687e8ee-5d5a-49ec-9032-c8b9a292b6ef

Body

externalReferenceIdentifier string

required

Payment instruction external reference identifier

customerUid string

required

Unique identifier for a customer

merchantUid string

required

Unique identifier for a merchant

amount number

required

Payment amount to be processed. Value must be a positive decimal

frequency object

required

Payment frequency model

nextBillingDate string

required

Next billing date when a payment should be processed from a customer's bank account. Must be in the future

recurringEndDate string

required

Recurring end date when a payment should stop being processed from a customer's bank account. Must be in the future

enableOptimalBillingDate boolean

required

Sets the next billing date based on the cash flow of the customer account and the amount and frequency of the transaction

POST /paymentinstructions

curl --request post \
--url https://app.waivr.co/api/waivr-app/v1/paymentinstructions \
--data '
{
"externalReferenceIdentifier": "pos-ref-19fbb695-ebe6-4c84-a32d-15403fed7ccc",
"customerUid": "53db8c10-9f7b-4dde-bb3a-6a9faf190ff6",
"merchantUid": "f021c403-0dbd-4654-9153-2f918579834f",
"amount": "17.54",
"frequency": {
"cycle": "MONTHLY",
"recurrence": "1"
},
"nextBillingDate": "",
"recurringEndDate": "", "enableOptimalBillingDate": "true"
}
'

curl --request post \ --url https://app.waivr.co/api/waivr-app/v1/paymentinstructions \ --data '{ "externalReferenceIdentifier": "pos-ref-19fbb695-ebe6-4c84-a32d-15403fed7ccc", "customerUid": "53db8c10-9f7b-4dde-bb3a-6a9faf190ff6", "merchantUid": "f021c403-0dbd-4654-9153-2f918579834f", "amount": "17.54", "frequency": { "cycle": "MONTHLY", "recurrence": "1" }, "nextBillingDate": "", "recurringEndDate": "", "enableOptimalBillingDate": "true"}'

Review a payment instruction

Headers

Accept string

required

Controls type of payload accepted by endpoint
Default: application/json

Authorization string

required

Authorization token that can be of two types: JWT or API
Default: <your key><your secret>

reqSessionId string

required

Request Session UUID to track call through logs
Default: b687e8ee-5d5a-49ec-9032-c8b9a292b6ef

Path Parameters

paymentInstructionUid string

required

Unique identifier for a payment instruction

GET /paymentinstructions/{paymentInstructionUid}

curl --request GET \
--url https://app.waivr.co/api/waivr-app/v1/paymentinstructions/{paymentInstructionUid} \
--header 'Accept: string' \
--header 'Authorization: string' \
--header 'Content-Type: application/json'

curl --request GET \ --url https://app.waivr.co/api/waivr-app/v1/paymentinstructions/{paymentInstructionUid} \ --header 'Accept: string' \ --header 'Authorization: string' \ --header 'Content-Type: application/json'

Update a payment instruction

Headers

Accept string

required

Controls type of payload accepted by endpoint
Default: application/json

Authorization string

required

Authorization token that can be of two types: JWT or API
Default: <your key><your secret>

reqSessionId string

required

Request Session UUID to track call through logs
Default: b687e8ee-5d5a-49ec-9032-c8b9a292b6ef

Path Parameters

paymentInstructionUid string

required

Unique identifier for a payment instruction

Body

status string

required

Payment instruction status

amount number

required

New payment amount to be applicable in the next billing cycle

customerUid string

required

Unique identifier for a customer

paymentInstructionUid string

required

Unique identifier for a payment instruction

paymentInstructionExternalRefId string

required

Unique identifier for a payment instruction

PATCH /paymentinstructions/{paymentInstructionUid}

curl --request patch \
--url https://app.waivr.co/api/waivr-app/v1/paymentinstructions/{paymentInstructionUid} \
‍ --data '
{
"status": "INACTIVE",
"amount": "12.99"
}
'

curl --request patch \ --url https://app.waivr.co/api/waivr-app/v1/paymentinstructions/{paymentInstructionUid} \ --data '{ "status": "INACTIVE", "amount": "12.99"}'

Payment

A payment is an object associated to a Customer and Payment Instruction. A payment is created if a bill is due at time the subscription begins and upon each recurring billing date.

Initiate a payment

Headers

Accept string

required

Controls type of payload accepted by endpoint
Default: application/json

Authorization string

required

Authorization token that can be of two types: JWT or API
Default: <your key><your secret>

reqSessionId string

required

Request Session UUID to track call through logs
Default: b687e8ee-5d5a-49ec-9032-c8b9a292b6ef

Body

paymentInstructionUid string

required

Unique identifier for a payment instruction

methodType string

required

Payment method type

POST /payments

curl --request post \
--url https://app.waivr.co/api/waivr-app/v1/payments \
--data '
{
"paymentInstructionUid": "34663686-3e7a-4b35-8412-357d6247273f",
"methodType": "ACH"
}
'

curl --request post \ --url https://app.waivr.co/api/waivr-app/v1/payments \ --data '{ "paymentInstructionUid": "34663686-3e7a-4b35-8412-357d6247273f", "methodType": "ACH"}'

Search for a payment

Headers

Accept string

required

Controls type of payload accepted by endpoint
Default: application/json

Authorization string

required

Authorization token that can be of two types: JWT or API
Default: <your key><your secret>

reqSessionId string

required

Request Session UUID to track call through logs
Default: b687e8ee-5d5a-49ec-9032-c8b9a292b6ef

Body

merchantUid string

required

Unique identifier for a merchant‍

customerUid string

required

Unique identifier for a customer

paymentInstructionExternalRefId string

required

Unique identifier for a payment instruction

paymentInstructionUid string

required

Unique identifier for a payment instruction

pagination object

Pagination model

POST /payments

curl --request post \
--url https://app.waivr.co/api/waivr-app/v1/payments \
--data '
{
"paymentInstructionUid": "34663686-3e7a-4b35-8412-357d6247273f",
"methodType": "ACH"
}
'

curl --request post \ --url https://app.waivr.co/api/waivr-app/v1/payments \ --data '{ "paymentInstructionUid": "34663686-3e7a-4b35-8412-357d6247273f", "methodType": "ACH"}'

View a payment

Headers

Accept string

required

Controls type of payload accepted by endpoint
Default: application/json

Authorization string

required

Authorization token that can be of two types: JWT or API
Default: <your key><your secret>

reqSessionId string

required

Request Session UUID to track call through logs
Default: b687e8ee-5d5a-49ec-9032-c8b9a292b6ef

Body

Uid string

required

Unique identifier for a payment‍

createDate string

required

Date payment was created

updateDate string

required

Date payment was last updated

status string

required

Payment cycle
Allowed values: NOT_INITIATED NOT_INITIATED_INSUFFICIENT_FUNDS NOT_INITIATED_DISCONNECTED_ACCOUNT INITIATED_PRE_FLIGHT INITIATED PENDING PROCESSED FAILED_ATTEMPT FAILED_SYSTEM‍

amount number

required

Payment amount to be processed

paymentDate string

required

Billing date‍

POST /payments

curl --request post \
--url https://app.waivr.co/api/waivr-app/v1/payments \
--data '
{
"paymentInstructionUid": "34663686-3e7a-4b35-8412-357d6247273f",
"methodType": "ACH"
}
'

curl --request post \ --url https://app.waivr.co/api/waivr-app/v1/payments \ --data '{ "paymentInstructionUid": "34663686-3e7a-4b35-8412-357d6247273f", "methodType": "ACH"}'

Errors

Waivr uses standard HTTP response status codes to indicate the success or failure of a request. Status codes in the 2xx denote a successful request. Status codes in the 4xx range denote a client error, e.g. a problem with the user access token, invalid payment instruction recurrence, etc. Status codes in the 5xx range denote a problem on our end, e.g. a payment could not be processed by the bank and it's not possible or otherwise doesn't make sense to gracefully handle the exception.

Error Types

400 - Bad request

Request could not be processed due to invalid information that is non-conforming with API contract.

401 - Unauthorized

Access to the resource is unauthorized, due to an invalid token or unauthorized access to the information.

404 - Not Found

Requested resource was not found.

409 - Conflict

Requested resource is in a conflicting state for the action requested.

422 - Unprocessable Entity

Action cannot be processed for the requested resource.

500 - Internal Server Error

Server encountered an unexpected condition.