Payanywhere Android SDK Server Functions

Payanywhere Android SDK

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

{
  "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

Get Base64 Image

get /accounts/{accountId}/image/{imageId}

Get a Base64 encrypted image of the given type. Requires Account ID, Image ID, Authorization, and a type query parameter.

Example Response

200 If request is authorized:

400 If request is authorized and accessing a wrong or non-existent image type

401 If the request is not authorized:

404 If request is authorized and accessing a wrong or non-existent image

Create Bulk Invoice Import

post /accounts/{accountId}/imports

Create a new bulk invoicing import from a CSV file. Requires Account ID, Authorization, a file, and a type. Optional transaction_source.

Request Schema

file

string

type

string

Example:

invoices

transaction_source

string

Example:

PH-Portal|6.9

latitude

number

Example:

42.564374

longitude

number

Example:

-83.127797

mapping

object

mapping_id

integer

Example:

1234

Example Request

{
  "file": "string",
  "type": "invoices",
  "transaction_source": "PH-Portal|6.9",
  "latitude": 42.564374,
  "longitude": -83.127797,
  "mapping": "object",
  "mapping_id": 1234
}

Example Response

201 If request is authorized:

400 When account id does not exist or is invalid, no CSV file provided, headers are missing, no type field, invalid mapping, or missing mapping name when save is set to true:

403 When user id does not exist or role isn't valid (cashier, customer service, or does not have access to invoices):

404 When mapping id does not exist, is inactive (ex. is was a one time mapping), or belongs to another merchant:

Get Bulk Import Records

get /accounts/{accountId}/imports

Get bulk import records. Requires Account ID and Authorization. Optional cursor and status query parameters.

Parameters

cursor

string

status

string

transaction_source

string

Example:

PH-Portal|6.9

Example Response

200 If request is authorized:

400 When user id or account id is invalid

403 When user role isn't valid (cashier, customer service, or does not have access to invoices)

404 When account id does not exist

Update Import (Send, Cancel, Discard, Fix Errors)

put /accounts/{accountId}/imports/{importId}

Send, cancel, discard, or fix errors on a bulk import. Requires Account ID, Import ID, Authorization, and an action.

Request Schema

action

string

Enum:

send

cancel

discard

fix-errors

transaction_source

string

Example:

PH-Portal|6.9

rowIndex

integer

Example:

rowValue

object

Example Request

{
  "action": {
    "enum": [
      "send",
      "cancel",
      "discard",
      "fix-errors"
    ]
  },
  "transaction_source": "PH-Portal|6.9",
  "rowIndex": 1,
  "rowValue": "object"
}

Example Response

201 If request is authorized:

400 When account id does not exist or is invalid, import does not exist, or import has already been canceled or discarded. When attempting to fix errors on an invoice that does not exist (rowIndex does not exist): {"reason": "Bad Request: Unknown error row index has been provided"}

403 When user id does not exist or role isn't valid (cashier, customer service, or does not have access to invoices):

Get Import

get /accounts/{accountId}/imports/{importId}

Get a bulk import by its ID. Requires Account ID, Import ID, Authorization, and an optional verbose and type query parameter.

Parameters

verbose

string

type

string

transaction_source

string

Example:

PH-Portal|6.9

Example Response

200 If request is authorized:

400 When user id or account id is invalid

403 When user role isn't valid (cashier, customer service, or does not have access to invoices)

404 count id or import id does not exist