Payment Tokens

The payment flow in general consists of creating a payment token that can then be claimed by the payee. The API focuses on tokens in order to let the format the token is transmitted in to be decided by the user facing layer, i.e. the UI apps. The token can be used in a link, turned into a QR code, etc.

For the GigPay wallet app, the link should the in the format of https://wallet.{env}.gigpay.com/payment/{token}. For production, env is blank meaning the slug is wallet.gigpay.com. For other environments, for example stage, the slug is wallet.stage.gigpay.com.

Currently tokens are generated one at a time - use cases looking to generate multiple payments should loop through the endpoint. We’re not sure what the theoretical rate limit is in the API but generating a token or two per second should be fine. We plan to introduce a batch token creation endpoint in the future.

Payment tokens are created through:

POST /api/v1/payment-tokens

{
  "assetType": "usd",
  "sourceAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "amount": 1,
  "expiresAtUtc": "2024-01-09T18:00:56.246Z",
  "memo": "string"
}

Currently only USD denominated payments are supported however expiration time for the token, account making the payment, the amount of the payment, and the memo are all configurable.

Payment tokens have a variety of statuses to indicate their stage in the lifecycle:

Active: from created until accepted/rejected or expired
Expired: token expires after some configurable interval
Rejected: when user rejects payment
Succeeded: when transaction completes
Closed: when the transaction fails in Masspay

Retrieving Payments

Payments can be retrieved through:

GET /api/v1/payments
{
  "data": [
    {
      "paymentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "amount": 0,
      "assetType": "usd",
      "status": "processing",
      "type": "deposit",
      "createdAtUtc": "2024-01-09T19:19:27.693Z",
      "modifiedAtUtc": "2024-01-09T19:19:27.693Z",
      "source": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "businessAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "userIdentityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "externalStorage": "string"
      },
      "destination": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "businessAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "userIdentityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "externalStorage": "string"
      },
      "paymentTokenId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],

Payments can have the following types:

Deposit: a payment from an external bank account (e.x. wire deposit into a business account)
Transfer: a payment from one account to another (e.x. a payment link from a payor to a payee
Withdrawal: a transfer to an offramp (e.x. Ach, wire, zelle)

As well as the following statuses:

Pending: transaction (withdrawal) is created in the GigPay API
Processing: when user accepts payment token (transfer created)
Completed: payment successfully completes
Canceled: transaction fails downstream in Masspay
Failed: when transfer fails for unexpected reasons

Currently, this will return all payments so filtering, sorting, etc should all be implemented by the integrator. At some point in the future, we’ll implement filtering parameters on the endpoint itself.