Invoicing API Specification

Invoicing API

Authentication

post /auth

This endpoint will return a JSON Web Token (JWT) that should be used with the Authorization header when sending requests that require authorization.

Request Schema

mid required

string

Example:

9999999999999

developerKey required

string

password required

string

Example Request

{
  "mid": "9999999999999",
  "developerKey": "<MY_DEVELOPER_KEY>",
  "password": "<MY_PASSWORD>"
}

Example Response

200 Request Authorized

400 Invalid Post Data

404 Unauthorized Request

Refresh Session

post /auth/refreshSession

This endpoint takes a previously-authorized JWT and creates a new JWT with an extended expiration date. Data stored within the token will stay the same and the user will still have access to the endpoints. To use this function, send a valid JWT through the Authorization header and replace your stored JWT with the token response upon success. This endpoint can only refresh valid JWTs signed by this application. Invalid or expired JWTs are unauthorized and will return as such.

Example Response

200 Valid Token

401 Unauthorized

End Session

get /auth/expireToken

This endpoint logs out of and expires a JWT. This requires a previously-authorized JWT. See the /auth endpoint for more information on obtaining a JWT.

Example Response

200 Request Authorized

401 Unauthorized

Refund or Void Transaction

post /accounts/{accountId}/transactions

This endpoint will void or refund a transaction. Transactions may be refunded if settlement has occurred or voided if settlement has not occurred. For any Sale or Preauth sent through the Payanywhere SDK, Payanywhere SDK will return the parameter “transactionUniqueId.” The “transactionUniqueId” has the format of “ccs_” followed by several numerical characters. For this request, you will need to parse the “transactionUniqueId” returned by the Payanywhere SDK, removing the “ccs_” portion of that string, and submit the remaining numerical value in the “transaction_id” field for Voids, or the “ccs_pk” field for Refunds.

For example, if the Payanywhere SDK returned “transactionUniqueId=ccs_87654321” then the “transaction_id” or “ccs_pk” for this request would equal “87654321”. Account ID is required to be inserted into this URL. Your Account ID will be returned from the Authentication request. Authorization is required for this endpoint. Use the JWT returned from the Authentication request.

For refunds, you can refund the full amount of the transaction or any amount less than the transaction amount. If you try and refund an amount greater than the transaction amount, a 400 error code will be returned with the message “Bad Request.”

Request Schema

type required

string

Enum:

void

refund

transaction_id required

number

Example:

87654321

comment

string

Example:

Some comment

username required

string

Example:

user@example.com

transaction_source

string

Example:

PA-iOS-SDK|5.10.0-x86_64-12.2

ccs_pk

number

Example:

87654321

amount

string

Example:

Example Request

Void Request

{
  "type": "void",
  "transaction_id": 87654321,
  "comment": "some comment",
  "username": "user@example.com",
  "transaction_source": "PA-iOS-SDK|5.10.0-x86_64-12.2"
}

Example Response

201 Authorized

401 Unauthorized. New JWT needed

404 Transaction_id not found

Create On-demand Invoices

post /accounts/{accountId}/invoices

Create on-demand invoices. Account ID is required to be inserted into this URL. Your Account ID will be returned from the Authentication request. Authorization is required for this endpoint. Use the JWT returned from the Authentication request.

Request Schema

type required

string

Minimum:

invoice required

object

Example Request

{
  "type": "ondemand",
  "qrcode": false,
  "invoice": {
    "latitude": 42.5304064,
    "longitude": -83.111936,
    "customer": {
      "first_name": "John",
      "last_name": "Smith",
      "email": "user@example.com",
      "phone": "12345678"
    },
    "name": "NAME",
    "description": "DESCRIPTION",
    "number": "NUMBER",
    "due_date": "2019-09-10",
    "send_date": "2019-09-09T04:00:00.000Z",
    "amount": 78,
    "tax_rate": 10,
    "service_fee_enabled": true
  }
}

Example Response

200 Authorized

401 Unauthorized