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://production.waivr.co/api/waivr-app

Sandbox:
https://sandbox.waivr.co/api/waivr-app

Merchant Settings

The Merchant Settings object allows you to view data defined at the merchant level, like Pay by Bank discount.

Find Merchant Settings

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

Response

200 - Successfully finds merchant settings

createDate string<date-time>

required

Date Merchant Settings was created.

discount object

required

Merchant Settings Payment Discount Model

uid string

required

Merchant Settings unique identifier.‍

updateDate string

required

Last date Merchant Settings was updated.

GET /v1/merchants/{merchantUid}/settings/summary

curl --request GET \
--url https://production.waivr.co/api/waivr-app/v1/merchants/merchantUid/settings/summary \
--header 'Accept: application/json' \
--header Authorization: <your key><your secret>' \
--header 'reqSessionId: a93bdaf7-fe24-4304-986f-e1a12d840d8b'
‍

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

{
"createDate": "2022-12-12T19:57:44.438588476Z",
"discount": {
"payment": 2
},
"uid": "53db8c10-9f7b-4dde-bb3a-6a9faf190ff6",
"updateDate": "2022-12-12T19:57:44.623806274Z"
}

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 /v1/customers

curl --request post \
--url https://production.waivr.co/api/waivr-app/v1/customers \
--data‍
{
"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"
}
}

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

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 /v1/connectaccounts/render

curl --request post \
--url https://production.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 or Update 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 /v1/connectaccounts/connect

curl --request post \
--url https://production.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 either active or inactive when the customer’s subscription is canceled or suspended.

Either a single payment instruction can be created, or a group of payment instructions can be created.

Create payment instructions

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

customerUid string

required

Unique identifier for a customer

merchantUid string

required

Unique identifier for a merchant

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.
‍Default: false

instructions array [object]

required

Group of payment instructions

Response

201 - Successfully creates Payment Instructions. If there is a group of instructions, there will be a section for each instruction in the payload.

Status string

required

Payment Instruction Status
‍Default: PENDING ACTIVE ON_HOLD INACTIVE

POST /v2/paymentinstructions

curl --request post \
--url https://production.waivr.co/api/waivr-app/v2/paymentinstructions \
--data '{
  "customerUid": "53db8c10-9f7b-4dde-bb3a-6a9faf190ff6",
"enableOptimalBillingDate": true,
"instructions": [
{
   "subtotalAmount": 17.54,
     "amount": 8.42,
"discountPercentage": 52,
"externalReferenceIdentifier": "pos-ref-19fbb695-ebe6-4c84-a32d-15403fed7ccc",
"frequency": {
"cycle": "MONTHLY",
"recurrence": 1
},
"nextBillingDate": "2023-01-12T19:57:44.623806274Z",
"recurringEndDate": "2023-12-12T19:57:44.623806274Z"
}
],
"merchantUid": "f021c403-0dbd-4654-9153-2f918579834f"
}'

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

Sample Response

{
"createDate": "2022-12-12T19:57:44.438588476Z",
"instructions": [
{
"subtotalAmount": 8.42,
"amount": 17.54,
"createDate": "2022-12-12T19:57:44.438588476Z",
"customerUid": "53db8c10-9f7b-4dde-bb3a-6a9faf190ff6",
"enableOptimalBillingDate": false,
"externalReferenceIdentifier": "pos-ref-19fbb695-ebe6-4c84-a32d-15403fed7ccc",
"frequency": {
"cycle": "MONTHLY",
"recurrence": 1
},
"merchantUid": "f021c403-0dbd-4654-9153-2f918579834f",
"metadata": {
"optimalBillingDateAnalysis": {
"basedNextBillingDate": "2022-02-12T19:57:44.623806274Z",
"optimalBillingDates": [
"2022-02-11T19:57:44.623806274Z",
"2022-02-12T19:57:44.623806274Z",
"2022-02-13T19:57:44.623806274Z"
]
}
},
"nextBillingDate": "2023-01-12T19:57:44.623806274Z",
"recurringEndDate": "2023-12-12T19:57:44.623806274Z",
"status": "PENDING",
"uid": "34663686-3e7a-4b35-8412-357d6247273f",
"updateDate": "2022-12-12T19:57:44.623806274Z"
}
],
"uid": "34663686-3e7a-4b35-8412-357d6247273f",
"updateDate": "2022-12-12T19:57:44.623806274Z"
}

View 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 /v1/paymentinstructions/{paymentInstructionUid}

curl --request GET \
--url https://production.waivr.co/api/waivr-app/v1/paymentinstructions/{paymentInstructionUid} \
--header 'Accept: application/json' \
--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

Body

subtotalAmount number

required

Payment instruction new subtotal amount to be applicable in the next billing cycle

amount number

required

Payment instruction new amount to be applicable in the next billing cycle

frequency object

required

Payment frequency model

status string

required

Payment Instruction updatable status
‍Allowed values: INACTIVE ON-HOLD

PATCH /v1/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://production.waivr.co/api/waivr-app/v1/paymentinstructions/{paymentInstructionUid} \
‍ --data '
{
"subtotalAmount": 6.99,
"amount": 12.99,
"frequency": {
"cycle": "MONTHLY",
"recurrence": 1
},
"status": "INACTIVE",
}
'

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

methodType string

required

Payment method type
‍Allowed Value: ACH

paymentInstructionGroupUid string

required

Unique identifier for a group of payment instructions

Response

201 - Successfully creates a payment and originates a money transference immediately.

202 - Successfully accepts a payment and money transference will be originated in the future. No response body.

amount number

required

Total payment amount to be processed, inclusive of discounts, taxes, and shipping.
‍Example: 17.54

createDate string<date-time>

required

Date payment was created
‍Example: 2022-12-12T19:57:44.438588476Z

paymentDate string<date-time>

required

Billing date
‍Example: 2022-12-12T19:57:44.438588476Z

status string

required

Status of payment
‍Allowed Values: NOT_INITIATED‍ PENDING PROCESSED FAILED

uuid string

required

Unique identifier for a payment
‍Example: 1b536510-29c8-4bde-ad85-047512af90d2

updateDate string<date-time>

required

Last date payment was updated
‍Example: 2022-12-12T19:57:44.623806274Z

POST /v2/payments

curl --request post \
--url https://production.waivr.co/api/waivr-app/v2/payments \
--data '
{
"paymentInstructionGroupUid": "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"}'

Sample Response

[
     {
       "amount": 17.54,
       "createDate": "2022-12-12T19:57:44.438588476Z",
       "paymentDate": "2022-12-12T19:57:44.438588476Z",
       "status": "NOT_INITIATED",
       "uid": "1b536510-29c8-4bde-ad85-047512af90d2",
       "updateDate": "2022-12-12T19:57:44.623806274Z"
     }
  ]

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 /v1/payments/search

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://production.waivr.co/api/waivr-app/v1/payments/search \
--data '
{
"customerUid": "53db8c10-9f7b-4dde-bb3a-6a9faf190ff6",
"merchantUid": "f021c403-0dbd-4654-9153-2f918579834f",
"pagination": {
"limit": 1,
"offset": 0
},
"paymentInstructionExternalRefId": "pos-ref-19fbb695-ebe6-4c84-a32d-15403fed7ccc",
"paymentInstructionUid": "34663686-3e7a-4b35-8412-357d6247273f"
}'

Sample Response

{
"content": [
{
"amount": 17.54,
"createDate": "2022-12-12T19:57:44.438588476Z",
"paymentDate": "2022-12-12T19:57:44.438588476Z",
"status": "NOT_INITIATED",
"uid": "1b536510-29c8-4bde-ad85-047512af90d2",
"updateDate": "2022-12-12T19:57:44.623806274Z"
}
],
"empty": true,
"first": true,
"last": true,
"number": 0,
"numberOfElements": 0,
"pageable": {
"offset": 0,
"pageNumber": 0,
"pageSize": 0,
"paged": true,
"sort": {
"empty": true,
"sorted": true,
"unsorted": true
},
"unpaged": true
},
"size": 0,
"sort": {
"empty": true,
"sorted": true,
"unsorted": true
}
}

View a payment

Path Parameters

paymentUid string

required

Unique identifier of 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

GET /v1/payments/{paymentUid}

curl --request GET \
--url https://production.waivr.co/api/waivr-app/v1/payments/{paymentUid} \
--header 'Accept: application/json' \
  --header 'Authorization: <your key> <your secret>' \
  --header 'Content-Type: application/json' \
  --header 'reqSessionId: 4f505437-20fb-473f-94d9-85920c2a2d55'

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

Sample Response

{
   "amount": 17.54,
   "createDate": "2022-12-12T19:57:44.438588476Z",
   "paymentDate": "2022-12-12T19:57:44.438588476Z",
       "status": "PROCESSED",
       "uid": "1b536510-29c8-4bde-ad85-047512af90d2",
       "updateDate": "2022-12-12T19:57:44.623806274Z"

}

Refund

A refund is an object associated to a Customer. A refund is created when an instruction is sent to move funds from a Merchant account to a Customer account.

Initiate a refund

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

amount number

required

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

customerUiD string

required

Unique identifier for a customer.

merchantUid string

required

Unique identifier for a merchant.

POST /v1/refunds

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://production.waivr.co/api/waivr-app/v1/refunds \
--data '
{
"amount": 17.54,
"customerUid": "53db8c10-9f7b-4dde-bb3a-6a9faf190ff6",
"merchantUid": "f021c403-0dbd-4654-9153-2f918579834f"
}
'

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.