Auth

API calls can be authenticated by either providing an API key in the “X-Api-Key” header or by providing a user access token in the “Authorization” header.

Org Accounts  API  accessed with a user access token require the “X-Centrapay-Account” header to be provided. The “X-Centrapay-Account” header specifies the unique identifier of the Centrapay Org Account.

Authenticate with API key
GET/api/account-memberships
curl -X GET https://service.centrapay.com/api/account-memberships \
  -H "X-Api-Key: $api_key"
Authenticate with user access token
GET/api/account-memberships
curl -X GET https://service.centrapay.com/api/account-memberships \
  -H "Authorization: $jwt"
Authenticate org account with user access token
GET/api/account-memberships
curl -X GET https://service.centrapay.com/api/account-memberships \
  -H "Authorization: $jwt" \
  -H "X-Centrapay-Account: Jaim1Cu1Q55uooxSens6yk"

API Keys  API  provide enduring access to a single Centrapay account.

The Centrapay test merchant API key is available to test creating payment requests: f32c5497297084e5354b47c40d5ccacb109ce483.

User access tokens provide time-limited access to all Centrapay accounts for which the user is a member. Access tokens are issued using OIDC code flow via the Centrapay OAuth authorization server and login page at auth.centrapay.com.

After successfully negotiating the OIDC code flow your application will have access to three tokens:

TokenDescription
Id TokenJWT containing user attributes such as id, phone and email.
Access TokenJWT granting access to Centrapay APIs. Expires after 1 hour.
Refresh TokenToken for OIDC token exchange. Expires after 60 days or when revoked.

A good starting point for learning more about OIDC is Okta’s OAuth OIDC Illustrated Guide.

When initiating a login request, a valid redirect URI must be provided. To obtain a dedicated OAuth client id with your application’s redirect URI(s) whitelisted please contact Centrapay support. Your callback URI can be for a website (such as ”https://yourapp.example.com/oidc-callback”) or mobile app (such as “com.example.yourapp://oidc-callback”).

Your application can use any OIDC client to negotiate the authentication flow but it must support OIDC authorization code flow with PKCE. See the Example OIDC Consumer guide for a working example using the “oidc-client” JavaScript library. The Centrapay authorization server configuration can be interrogated via https://auth.centrapay.com/.well-known/openid-configuration.

When handling the OIDC callback, browser based applications should slurp the callback parameters by performing a location.replace() so they are not available in the browser’s location bar or browsing history. If your application needs to talk directly to service.centrapay.com from a browser then it will also need to be whitelisted for cross-origin requests.

Claims

The following table lists the claims which may be be included in a user id token. At minimum, the “sub” claim and one of “phone_number” or “email” will be present.

NameDescription
subCentrapay user id
emailemail address
phone_numberphone number
given_namegiven name(s)
family_namesurname
preferred_usernameCentrapay user handle
phone_number_verifiedphone number has been verified (can be used for account recovery)
email_verifiedemail has been verified (can be used for account recovery)

Users and API keys are assigned a role for their associated Centrapay account(s). The permissions granted to the roles are shown in the table below.

Most permissions apply only to resources owned by the associated account. Some permissions, such as payment-requests:pay, apply globally to all resources regardless of the account the resource belongs to. The global permissions are indicated below with a star (✸).

Account Flags

Some permissions require an additional flag associated to their individual account or the targeted account that owns the resource (they may be the same account). For each permission, if there is a flag associated to it then at least one of them must be met.

SymbolDescription
👤A trusted user flag on the individual account, obtained by verifying a NZ phone number.
🧀An external-asset-issuer subscription on the targeted Account, obtained by contacting centrapay.
🗄The targeted account must be of type org.
🪙A collection-manager subscription on the targeted Account, obtained by contacting centrapay.

Permissions

PermissionAccount OwnerAnon ConsumerMerchant TerminalExternal Asset ProviderCashier
accounts:create
accounts:read
accounts:updat
api-keys:create
api-keys:list
api-keys:update
asset-transfers:claim
asset-transfers:create 👤 🧀
asset-transfers:read
assets:read
assets:spend 👤
bank-account-approvals:create
bank-account-requests:authorize
bank-account-requests:create
bank-accounts:create
bank-accounts:read
bank-accounts:update
business:create
business:update
business:read
collections:create 🪙
collections:read 🪙
external-assets:create 👤 🧀
external-assets:update
integration-requests:configure
integration-requests:create 🗄
integration-requests:read 🗄
invitations:accept✅ ✸
invitations:read✅ ✸
media-uploads:create
memberships:delete 🗄
memberships:update
merchants:create 🗄
merchants:list 🗄
merchants:read 🗄
merchants:update 🗄
loyalty-programs:create 🗄
loyalty-programs:read 🗄
patron-codes:create
patron-codes:read
payment-activities:read
payment-conditions:approve
payment-requests:cancel 🗄
payment-requests:create 🗄✅ ✸
payment-requests:pay 🗄✅ ✸✅ ✸✅ ✸
payment-requests:read✅ ✸✅ ✸✅ ✸✅ ✸
payment-requests:read-by-shortcode
payment-requests:refund 🗄
payment-requests:void 🗄
payment-requests:release 🗄
payment-requests:confirm 🗄
quotas:read
redemption-conditions:create 🪙
scanned-code:decode
tokens:create 🪙
topups:read
wallets:create
wallets:deposit
wallets:read
wallets:transfer 👤
wallets:withdraw