diff --git a/markdoc.config.mjs b/markdoc.config.mjs index be8322bbb..31fa02180 100644 --- a/markdoc.config.mjs +++ b/markdoc.config.mjs @@ -104,6 +104,7 @@ export default defineMarkdocConfig({ property: { render: component('./src/components/Property.astro'), attributes: { + deprecated: { type: Boolean }, experimental: { type: Boolean }, name: { type: String }, required: { type: Boolean }, diff --git a/src/content/api/account-memberships.mdx b/src/content/api/account-memberships.mdoc similarity index 61% rename from src/content/api/account-memberships.mdx rename to src/content/api/account-memberships.mdoc index b1baabf69..c85bf6e37 100644 --- a/src/content/api/account-memberships.mdx +++ b/src/content/api/account-memberships.mdoc @@ -5,12 +5,6 @@ nav: path: Accounts order: 2 --- -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Error from '../../components/Error.astro'; -import Endpoint from '../../components/Endpoint.astro'; -import Badge from '../../components/Badge.astro'; - An Account Membership represents a user having access to a Centrapay [Account](/api/accounts/). An Account Membership has a role which grants the user access to some or all of the operations and resources within the account. @@ -20,131 +14,131 @@ some or all of the operations and resources within the account. A Member contains extended information about a user's access to an account. - - +{% properties %} + {% property name="accountId" type="string" %} The id of the [Account](/api/accounts/) the Membership is scoped to. - + {% /property %} - + {% property name="accountType" type="string" %} The type of the [Account](/api/accounts/) the Membership is scoped to. - + {% /property %} - + {% property name="accountName" type="string" %} The name of the [Account](/api/accounts/) the Membership is scoped to. - + {% /property %} - + {% property name="userId" type="string" %} The id of the user the Membership belongs to. - + {% /property %} - + {% property name="role" type="string" %} The role governing Membership permissions. - + {% /property %} - + {% property name="subject" type="crn" %} User or API key resource name for the membership. - + {% /property %} - + {% property name="createdAt" type="timestamp" %} When the Membership was created. - + {% /property %} - + {% property name="createdBy" type="crn" %} Resource that created the member. - + {% /property %} - + {% property name="modifiedAt" type="timestamp" %} When the Membership was last modified. - + {% /property %} - + {% property name="modifiedBy" type="crn" %} Resource that last modified the account member. - + {% /property %} - + {% property name="testAccount" type="boolean" %} A flag which is present if the [Account](/api/accounts/) is test. - + {% /property %} - + {% property name="firstName" type="string" %} First name of the user the membership belongs to. - + {% /property %} - + {% property name="lastName" type="string" %} Last name of the user the membership belongs to. - + {% /property %} - + {% property name="email" type="string" %} Email of the user the membership belongs to. - - + {% /property %} +{% /properties %} --- - - ## Add Member +%} + ## Add Member {% badge type="experimental" /%} This endpoint allows you to add or update the membership of a user to an account. - - + {% properties %} + {% property name="userId" type="string" required=true %} The id of the user the Membership belongs to. - + {% /property %} - + {% property name="role" type="string" required=true %} The role governing Membership permissions. - - - + {% /property %} + {% /properties %} +{% /endpoint %} --- - +%} ## List members This endpoint allows you to retrieve the list memberships to an account. - +{% /endpoint %} --- - +%} ## Revoke Member This endpoint allows you to revoke a users membership to an account. - - + {% properties heading="Errors" %} + {% error code="403" message="LAST_OWNER_NOT_REVOKABLE" %} The last remaining membership to an account cannot be revoked. - - - + {% /error %} + {% /properties %} +{% /endpoint %} --- - +%} ## List Account Memberships for Authenticated Subject This endpoint allows you to retrieve the accounts that the authenticated subject is a member of. - +{% /endpoint %} --- - +%} ## List Account Memberships for a User This endpoint allows you to retrieve the accounts that a user is a member of. - +{% /endpoint %} diff --git a/src/content/api/accounts.mdx b/src/content/api/accounts.mdoc similarity index 58% rename from src/content/api/accounts.mdx rename to src/content/api/accounts.mdoc index ab60c1ccf..5436ab9a3 100644 --- a/src/content/api/accounts.mdx +++ b/src/content/api/accounts.mdoc @@ -5,11 +5,6 @@ nav: path: Accounts order: 1 --- -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Error from '../../components/Error.astro'; -import Endpoint from '../../components/Endpoint.astro'; - An Account represents a permission boundary around Centrapay resources. Accounts can have [API Keys](/api/api-keys/) and [Account Memberships](/api/account-memberships/) which grant access to the resources. @@ -19,147 +14,147 @@ individual account. ## Account Model - - +{% properties %} + {% property name="id" type="string" %} The unique identifier. - + {% /property %} - + {% property name="type" type="string" %} Account type, must be either 'org' or 'individual'. - + {% /property %} - + {% property name="name" type="string" %} The display name of the Account. - + {% /property %} - + {% property name="region" type="string" %} The region that the Account will operate in. - + {% /property %} - + {% property name="test" type="boolean" %} A flag which is only present if the Account is for testing. - + {% /property %} - + {% property name="createdAt" type="timestamp" %} When the Account was created. - + {% /property %} - + {% property name="modifiedAt" type="timestamp" %} When the Account was updated. - + {% /property %} - + {% property name="createdBy" type="crn" %} The User or API Key that created the Account. - + {% /property %} - + {% property name="modifiedBy" type="crn" %} The User or API Key that updated the Account. - + {% /property %} - + {% property name="subscriptions" type="array" %} A list of [Subscriptions](#subscription-model) on the Account. - + {% /property %} - + {% property name="parentAccountId" type="string" %} The unique identifier of the parent account to which the current account is linked. This field establishes a hierarchical relationship between accounts, indicating that the current account was created by the specified parent account. - - + {% /property %} +{% /properties %} --- ## Subscription Model - - +{% properties %} + {% property name="name" type="string" %} The name of the Subscription. - - + {% /property %} +{% /properties %} --- - +%} ## Create an Account This endpoint allows you to create an Account. - - + {% properties %} + {% property name="name" type="string" required=true %} The name of the Account. - + {% /property %} - + {% property name="type" type="string" required=true %} Account type, must be either "org" or "individual". - + {% /property %} - + {% property name="owner" type="string" %} Id of user to add as member with "account-owner" role. - + {% /property %} - + {% property name="test" type="boolean" %} A flag indicating if the Account is for testing. Test Accounts will not be able to create non-test Accounts. - + {% /property %} - + {% property name="region" type="string" %} The region that the Account will operate in. Required for 'org' Accounts, not allowed for 'individual' Accounts. Can be "NZ", "AU", or "US". - - - + {% /property %} + {% /properties %} +{% /endpoint %} --- - +%} ## Get an Account This endpoint allows you to retrieve an Account. - +{% /endpoint %} --- - +%} ## Update an Account This endpoint allows you to update an account. - - + {% properties %} + {% property name="name" type="string" required=true %} The name of the Account. - - - + {% /property %} + {% /properties %} +{% /endpoint %} --- - +%} ## Update Subscriptions This endpoint allows you to update the subscriptions on an account. - - + {% properties %} + {% property name="subscriptions" type="array" required=true %} The list of subscriptions to assign to the account. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="INVALID_ACCOUNT_ID" %} The account does not exist. - + {% /error %} - + {% error code="403" message="INVALID_SUBSCRIPTION" %} One of the subscriptions in the list is not valid. - - - + {% /error %} + {% /properties %} +{% /endpoint %} diff --git a/src/content/api/api-keys.mdx b/src/content/api/api-keys.mdoc similarity index 59% rename from src/content/api/api-keys.mdx rename to src/content/api/api-keys.mdoc index c62a86a6d..44c211f15 100644 --- a/src/content/api/api-keys.mdx +++ b/src/content/api/api-keys.mdoc @@ -5,98 +5,94 @@ nav: path: API order: 6 --- -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Endpoint from '../../components/Endpoint.astro'; - API keys provide enduring access to a single Centrapay [Account](/api/accounts). ## API Key Model - - +{% properties %} + {% property name="accountId" type="string" %} The id of the Centrapay [Account](/api/accounts) the API Key is scoped to. - + {% /property %} - + {% property name="name" type="string" %} The alphanumeric name of the API key, must be unique within the account. - + {% /property %} - + {% property name="role" type="string" %} Supported roles are: "account-owner" and "merchant-terminal". See [Auth Permissions](/api/auth#permissions) for role details. - + {% /property %} - + {% property name="enabled" type="boolean" %} Flag indicating the API Key is usable for authentication. - + {% /property %} - + {% property name="createdAt" type="timestamp" %} When the API Key was created. - + {% /property %} - + {% property name="createdBy" type="crn" %} The User or API Key that created the API Key. - + {% /property %} - + {% property name="modifiedAt" type="timestamp" %} When the API Key was modified. - + {% /property %} - + {% property name="modifiedBy" type="crn" %} The User or API Key that modified the API Key. - + {% /property %} - + {% property name="version" type="string" %} An API Key version that is incremented when the API Key is updated. - - + {% /property %} +{% /properties %} --- - +%} ## Create an API Key This endpoint allows you to create an API key. - - + {% properties %} + {% property name="name" type="string" required=true %} The alphanumeric name of the API key, must be unique within the account. - + {% /property %} - + {% property name="role" type="string" required=true %} Supported roles are: "account-owner" and "merchant-terminal". See [Auth Permissions](/api/auth#permissions) for role details. - - - + {% /property %} + {% /properties %} +{% /endpoint %} --- - +%} ## List API Keys This endpoint allows you to list all API Keys for an Account. - +{% /endpoint %} --- - +%} ## Update an API Key This endpoint allows you to enable or disable an API key. - - + {% properties %} + {% property name="enabled" type="boolean" required=true %} Flag indicating the API Key is usable for authentication. - - - + {% /property %} + {% /properties %} +{% /endpoint %} diff --git a/src/content/api/asset-activities.mdx b/src/content/api/asset-activities.mdoc similarity index 69% rename from src/content/api/asset-activities.mdx rename to src/content/api/asset-activities.mdoc index 272252962..f10bd0c96 100644 --- a/src/content/api/asset-activities.mdx +++ b/src/content/api/asset-activities.mdoc @@ -5,44 +5,37 @@ nav: path: Assets order: 7 --- - -import Badge from '../../components/Badge.astro'; -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Endpoint from '../../components/Endpoint.astro'; -import Error from '../../components/Error.astro'; - Asset Activities are actions that have been taken in relation to an asset. These range from transactions, to status changes, to redemption of an asset. ## Asset Activity Model All Asset Activities extend this base model. This contains all properties that are shared between the activities - - +{% properties %} + {% property name="assetId" type="string" %} ID of the Asset the activity is for - + {% /property %} - + {% property name="activityNumber" type="string" %} Unique sequential Asset activity number - + {% /property %} - + {% property name="createdAt" type="timestamp" %} When the Activity was created. - + {% /property %} - + {% property name="createdBy" type="string" %} The service that created the activity - + {% /property %} - + {% property name="activityType" type="string" %} The [Asset Activity Type](#asset-activity-types) - + {% /property %} - + {% property name="accountId" type="string" %} The account that owns the asset - - + {% /property %} +{% /properties %} ## Asset Transaction Activity Model @@ -57,129 +50,129 @@ number. This extends the [asset activity model](#asset-activity-model) - - +{% properties %} + {% property name="ref" type="string" %} ID of the Centrapay resource that initiated the transaction. - + {% /property %} - + {% property name="refType" type="string" %} Name of the Centrapay resource that initiated the transaction. - + {% /property %} - + {% property name="type" type="string" %} Type of the Asset Transaction. Supported values are `increment-balance`, `decrement-balance` and `transfer`. - + {% /property %} - + {% property name="kind" type="string" %} Human readable value indicating the reason for the transaction. - + {% /property %} - + {% property name="srcAssetId" type="string" %} ID of the source asset. - + {% /property %} - + {% property name="destAssetId" type="string" %} ID of the destination asset. - + {% /property %} - + {% property name="srcParty" type="string" %} Display value for party providing funds. - + {% /property %} - + {% property name="destParty" type="string" %} Display value for party receiving funds. - + {% /property %} - + {% property name="otherParty" type="string" %} Display value for party providing or receiving funds. - + {% /property %} - + {% property name="amount" type="string" %} Amount of transaction in cents. - - + {% /property %} +{% /properties %} ## Token Refunded Activity Model This records the refunding of a token. Used when activityType is `token`. This extends the [Asset Activity Model](#asset-activity-model) - - +{% properties %} + {% property name="idempotencyKey" type="string" %} Client-supplied identifier that prevents double creation - + {% /property %} - + {% property name="action" type="string" %} type of action for token activities. Will be `refund` for all new activities - - + {% /property %} +{% /properties %} ## Token Redeemed Activity Model This records the redeeming of a token. Used when activityType is `token-redeemed`. This extends the [Asset Activity Model](#asset-activity-model) - - +{% properties %} + {% property name="idempotencyKey" type="string" %} Client-supplied identifier that prevents double creation. - + {% /property %} - + {% property name="lineItems" type="array" %} The [Line Items](/api/payment-requests/#line-item-model) being paid for - - + {% /property %} +{% /properties %} ## Asset Created Activity Model This records the creation of an asset. Used when activityType is `created`. This extends the [Asset Activity Model](#asset-activity-model) - - +{% properties %} + {% property name="status" type="string" %} The current status of the asset - - + {% /property %} +{% /properties %} ## Asset Received Activity Model This records the receiving of an asset. Used when activityType is `received`. This extends the [Asset Activity Model](#asset-activity-model) - - +{% properties %} + {% property name="recipientAlias" type="string" %} The alias of the user who received the asset - - + {% /property %} + {% property name="recipientAccountId" type="string" %} The accountId of the user who received the asset - - + {% /property %} + {% property name="senderAccountId" type="string" %} The accountId of the user who sent the asset - - + {% /property %} + {% property name="sender" type="string" %} The name of the user who sent the asset - - + {% /property %} + {% property name="status" type="string" %} The current status of the asset - - + {% /property %} +{% /properties %} ## Asset Sent Activity Model This records the sending of an asset. Used when activityType is `sent`. This extends the [Asset Activity Model](#asset-activity-model) - - +{% properties %} + {% property name="recipientAlias" type="string" %} The alias of the user who received the asset - - + {% /property %} + {% property name="senderAccountId" type="string" %} The accountId of the user who sent the asset - - + {% /property %} + {% property name="sender" type="string" %} The name of the user who sent the asset - - + {% /property %} + {% property name="status" type="string" %} The current status of the asset - - + {% /property %} +{% /properties %} ### Asset Activity Types @@ -199,30 +192,30 @@ This records the sending of an asset. Used when activityType is `sent`. This ext --- - - ## List Asset Transactions +%} + ## List Asset Transactions {% badge type="experimental" /%} Returns a [paginated](/api/pagination) list of [Asset Transactions](#asset-transaction-activity-model). This endpoint is currently only supported for `quartz` asset types. - +{% /endpoint %} --- - +%} ## List Asset Activities Returns a [paginated](/api/pagination) list of [Asset Activities](#asset-activity-model). ### Query Parameters - - + {% properties %} + {% property name="bankAccountId" type="string" %} The bankAccountId of the assets that activities should be returned for. - - - + {% /property %} + {% /properties %} +{% /endpoint %} diff --git a/src/content/api/asset-transfers.mdx b/src/content/api/asset-transfers.mdoc similarity index 59% rename from src/content/api/asset-transfers.mdx rename to src/content/api/asset-transfers.mdoc index eaac57694..8158096ba 100644 --- a/src/content/api/asset-transfers.mdx +++ b/src/content/api/asset-transfers.mdoc @@ -5,13 +5,6 @@ nav: path: Assets order: 2 --- - -import Badge from '../../components/Badge.astro'; -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Endpoint from '../../components/Endpoint.astro'; -import Error from '../../components/Error.astro'; - An asset transfer is an asynchronous exchange of an asset or an amount to a recipient. A recipient is an existing Centrapay user or someone who can create an account to claim the asset transfer by verifying @@ -22,79 +15,79 @@ message fields are scrubbed to avoid storing PII. ## Asset Transfer Model - - +{% properties %} + {% property name="id" type="string" %} The unique identifier. - + {% /property %} - + {% property name="status" type="string" %} The status of the Asset Transfer. See [Asset Transfer lifecycle](#asset-transfer-lifecycle) for possible values. - + {% /property %} - + {% property name="value" type="bignumber" %} Amount to send. Required for money transfers. Units depend on the asset type. - + {% /property %} - + {% property name="assetId" type="string" %} Id of a discrete asset to transfer or wallet to draw from. - + {% /property %} - + {% property name="assetType" type="string" %} The [Asset Type](/api/asset-types/) being transferred. - + {% /property %} - + {% property name="description" type="string" %} Shows up in transaction history against the transfer. 200 character limit. - + {% /property %} - + {% property name="message" type="string" %} Shows up in transaction history against the transfer. 100 character limit. - + {% /property %} - + {% property name="lastSentTo" type="string" %} The phone number or email address of the last recipient. - + {% /property %} - + {% property name="senderAlias" type="string" %} Phone number, email or handle of sender and who receives a request for asset transfer - + {% /property %} - + {% property name="senderName" type="string" %} Human readable name for the sender. 30 character limit. - + {% /property %} - + {% property name="recipientAccountId" type="string" %} The Centrapay Account id of the recipient. - + {% /property %} - + {% property name="senderAccountId" type="string" %} The Centrapay Account id of the sender. - + {% /property %} - + {% property name="claimedByAccountId" type="string" %} The Centrapay Account that claimed the Asset Transfer. - + {% /property %} - + {% property name="recipientAlias" type="string" %} Phone number, email or handle of receiver and who make a request for asset transfer - + {% /property %} - + {% property name="createdAt" type="timestamp" %} When the Asset Transfer was created. - + {% /property %} - + {% property name="updatedAt" type="timestamp" %} When the Asset Transfer was updated. - + {% /property %} - + {% property name="suppressNotification" type="boolean" %} Suppress notifications from Centrapay (SMS/Email). - + {% /property %} - + {% property name="url" type="string" %} A URL where the asset can be claimed if a recipient is not supplied. - - + {% /property %} +{% /properties %} --- @@ -116,115 +109,115 @@ Asset Transfer goes through different lifecycle stages. --- - - ## Request an Asset Transfer +%} + ## Request an Asset Transfer {% badge type="experimental" /%} Request a transfer of an asset from a sender to the recipient. - - + {% properties %} + {% property name="recipientAlias" type="string" required=true %} Contact information, such as phone number, email, or handle, for the individual requesting asset transfer. Currently supports bank account number only. - + {% /property %} - + {% property name="senderAccountId" type="string" required=true %} The account id of the sender who receives the request from recipientAlias. - + {% /property %} - + {% property name="assetType" type="string" required=true %} The type of asset being transferred. Currently, supports only `quartz.nzd` assets - + {% /property %} - + {% property name="description" type="string" %} Shows up in transaction history against the transfer. 200 character limit. - + {% /property %} - + {% property name="message" type="string" %} Shows up in transaction history against the transfer. 100 character limit. - + {% /property %} - + {% property name="suppressNotification" type="boolean" %} Suppress notifications from Centrapay (SMS/Email). - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="SENDER_NOT_FOUND" %} The requests must include a valid sender alias. - + {% /error %} - + {% error code="403" message="INVALID_ASSET_TYPE" %} The [asset's type](/api/asset-types/) does not support transfers. - - - + {% /error %} + {% /properties %} +{% /endpoint %} --- - - ## Accept an Asset Transfer Request +%} + ## Accept an Asset Transfer Request {% badge type="experimental" /%} - - + {% properties %} + {% property name="assetId" type="string" required=true %} Id of the asset to pay the asset transfer request with. Only valid for `quartz.nzd` assets - + {% /property %} - + {% property name="senderName" type="string" required=true %} Human readable name for the sender. 30 character limit. - + {% /property %} - + {% property name="value" type="bignumber" %} Amount to send. Required if not defined in the request; forbidden if it was. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="ASSET_TRANSFER_REQUEST_EXPIRED" %} The asset transfer request has already expired - + {% /error %} - + {% error code="403" message="ASSET_TRANSFER_REQUEST_ACCEPTED" %} The asset transfer request has already been accepted - + {% /error %} - + {% error code="403" message="BANK_ACCOUNT_BALANCE_INSUFFICIENT" %} The bank account the asset is for does not have enough balance for the transfer - + {% /error %} - + {% error code="403" message="QUOTA_EXCEEDED" %} The asset transfer would exceed the provided assets quotas - + {% /error %} - + {% error code="403" message="ASSET_NOT_ACTIVE" %} The asset is not active. - + {% /error %} - + {% error code="403" message="INVALID_ASSET_TYPE" %} The [asset's type](/api/asset-types/) does not match the request. - + {% /error %} - + {% error code="403" message="VALUE_NOT_DEFINED" %} The value of the asset transfer was not defined in either the initial request or the acceptance - + {% /error %} - + {% error code="403" message="VALUE_ALREADY_DEFINED" %} The value of the asset transfer was defined in both the initial request and the acceptance - - - + {% /error %} + {% /properties %} +{% /endpoint %} --- - +%} ## Create an Asset Transfer Transfer an asset to a recipient. Some assets can be transfered only in whole @@ -233,105 +226,105 @@ Asset Transfer goes through different lifecycle stages. Some assets can be transferred without supplying a recipient. A `url` field will be returned in these cases. The `url` will link to a page to claim the asset. - - + {% properties %} + {% property name="assetId" type="string" required=true %} Id of a discrete asset to transfer or wallet to draw from. - + {% /property %} - + {% property name="recipientAlias" type="string" %} Phone number, email or handle of receiver. - + {% /property %} - + {% property name="description" type="string" %} Shows up in transaction history against the transfer. 200 character limit. - + {% /property %} - + {% property name="message" type="string" %} Shows up in transaction history against the transfer. 100 character limit. - + {% /property %} - + {% property name="value" type="bignumber" %} Amount to send. Required for money transfers. Units depend on the asset type. - + {% /property %} - + {% property name="senderName" type="string" %} Human readable name for the sender. 30 character limit. - + {% /property %} - + {% property name="suppressNotification" type="boolean" %} Suppress notifications from Centrapay (SMS/Email). - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="INSUFFICIENT_WALLET_BALANCE" %} The value of the asset-transfer exceeds the balance on the wallet. - + {% /error %} - + {% error code="403" message="QUOTA_EXCEEDED" %} The transfer exceeds one or more spend quota limits. See [Quota Error Response](/api/quotas#errors). - + {% /error %} - + {% error code="403" message="ASSET_NOT_ACTIVE" %} The asset is not active and cannot be transferred. - + {% /error %} - + {% error code="403" message="RECIPIENT_MISSING" %} The asset must be transferred with a recipient supplied. - + {% /error %} - + {% error code="403" message="INVALID_ASSET_TYPE" %} The [asset's type](/api/asset-types/) does not support transfers. - - - + {% /error %} + {% /properties %} +{% /endpoint %} --- - +%} ## Get an Asset Transfer - +{% /endpoint %} --- - +%} ## Get Asset Transfer Summary - +{% /endpoint %} --- - - ## Claim Asset Transfer +%} + ## Claim Asset Transfer {% badge type="experimental" /%} Claim the asset transfer for the caller's authorised account. - - + {% properties heading="Errors" %} + {% error code="403" message="ASSET_TRANSFER_INVALID_RECIPIENT" %} The asset transfer already has a recipient defined through the `recipientAlias` field and cannot be claimed with this API. - - + {% /error %} + {% error code="403" message="ASSET_TRANSFER_INVALID_STATUS" %} The asset transfer is not in a `sent` status and hence cannot be claimed. - - - + {% /error %} + {% /properties %} +{% /endpoint %} --- - - ## Resolve Claimable Assets +%} + ## Resolve Claimable Assets {% badge type="experimental" /%} When you send another centrapay user cash or assets, they're automatically assigned to them. However, if they're not signed up yet then these assets are not immediately assigned. @@ -339,40 +332,40 @@ Asset Transfer goes through different lifecycle stages. If unclaimed, asset transfers are returned after 2 weeks. New accounts should call this endpoint to allocate assets that you've been sent. - +{% /endpoint %} --- - - ## List Asset Transfers +%} + ## List Asset Transfers {% badge type="experimental" /%} Returns a [paginated](/api/pagination/) list of Asset Transfers. - - + {% properties %} + {% property name="recipientAccountId" type="string" %} The Centrapay Account id of the recipient. - + {% /property %} - + {% property name="senderAccountId" type="string" %} The Centrapay Account id of the sender. - - - + {% /property %} + {% /properties %} +{% /endpoint %} --- - +%} ## Cancel an Asset Transfer - - + {% properties heading="Errors" %} + {% error code="403" message="INVALID_ASSET_TRANSFER_STATUS" %} The asset transfer status is invalid and cannot be cancelled. - - - + {% /error %} + {% /properties %} +{% /endpoint %} diff --git a/src/content/api/asset-types.mdx b/src/content/api/asset-types.mdoc similarity index 100% rename from src/content/api/asset-types.mdx rename to src/content/api/asset-types.mdoc diff --git a/src/content/api/assets.mdx b/src/content/api/assets.mdoc similarity index 61% rename from src/content/api/assets.mdx rename to src/content/api/assets.mdoc index 9a20bdc01..29bb335fc 100644 --- a/src/content/api/assets.mdx +++ b/src/content/api/assets.mdoc @@ -5,13 +5,6 @@ nav: path: Assets order: 1 --- - -import Badge from '../../components/Badge.astro'; -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Endpoint from '../../components/Endpoint.astro'; -import Error from '../../components/Error.astro'; - Centrapay digital assets are resources that represent the ability for a Centrapay account to perform transactions where value is exchanged. Assets can be spent to satisfy [Payment Requests](/api/payment-requests), withdrawn to a bank account via @@ -24,51 +17,51 @@ rules governing how it can be obtained, shared or spent. ## Asset Model All assets have the following fields along with the additional fields that are -specific to its category. Assets which don't have a category are considered +specific to its category. Assets which don't have a category are considered {% badge type="experimental" /%} and the model may change. - - +{% properties %} + {% property name="id" type="string" %} The Asset's unique identifier. - + {% /property %} - + {% property name="accountId" type="string" %} The Asset's owning Centrapay Account id. - + {% /property %} - + {% property name="category" type="string" %} Asset category ("money", "giftcard", "token"). - + {% /property %} - + {% property name="type" type="string" %} [Asset Type](/api/asset-types) id used by payment option asset types. - + {% /property %} - + {% property name="liveness" type="string" %} Either "main" (live payments allowed) or "test". - + {% /property %} - + {% property name="description" type="string" %} Displayable asset description. - + {% /property %} - + {% property name="createdAt" type="timestamp" %} Date when the asset was created or issued. - + {% /property %} - + {% property name="status" type="string" %} "active" if the asset can be used for payments. - + {% /property %} - + {% property name="meta" type="object" experimental=true %} Additional data that may only appear in the [Get Asset](#get-asset) response. - + {% /property %} - + {% property name="name" type="string" experimental=true %} The name of the asset when created from an [enduring payment consent](/api/bank-account-connection-intents#bank-account-connection-intent-types). Only valid for `quartz.nzd` assets. - - + {% /property %} +{% /properties %} --- @@ -81,187 +74,187 @@ and does not expire. Money assets have the following attributes along with the base asset fields. - - +{% properties %} + {% property name="currency" type="string" %} Currency code, eg "NZD". - + {% /property %} - + {% property name="balance" type="BigNumber" %} Current balance in the currency's smallest denomination (ie. cents). - + {% /property %} - + {% property name="availableBalance" type="BigNumber" %} The balance of the asset that is available for transfers or purchases. - + {% /property %} - + {% property name="settlement" type="boolean" experimental=true %} The asset is configured for [Settlements](/api/wallets#settlement-wallets). - + {% /property %} - + {% property name="period" type="string" experimental=true %} The period after which the `balance` will be reset. This field is only available on the [quartz](/api/asset-types) asset type. Possible values are `daily`, `weekly`, `fortnightly`, `monthly` or `yearly`. - + {% /property %} - + {% property name="periodStartedAt" type="timestamp" experimental=true %} Datetime when the current period was started. This field is only available on the [quartz](/api/asset-types) asset type. - + {% /property %} - + {% property name="periodEndingAt" type="timestamp" experimental=true %} Datetime when the current period will end. This field is only available on the [quartz](/api/asset-types) asset type. - - + {% /property %} +{% /properties %} --- -## Token Model +## Token Model {% badge type="experimental" /%} Tokens are assets which can only be spent in full. Every token is associated with a collection, which defines the branding and general rules for the tokens, such as active duration. Tokens have the following attributes along with the base asset fields. - - +{% properties %} + {% property name="collectionId" type="string" %} The [token collection](/api/tokens#token-collection-model) that will govern the branding and redemption rules for the token. - + {% /property %} - + {% property name="createdBy" type="crn" %} The identity that created the activity. - + {% /property %} - + {% property name="activeFrom" type="timestamp" %} The date when the asset becomes spendable. - + {% /property %} - + {% property name="expiresAt" type="timestamp" %} The date when the asset expires. - + {% /property %} - + {% property name="img" type="string" %} The img URL of the token. - + {% /property %} - + {% property name="issuer" type="string" %} The name of the [Business](/api/businesses) that issued the token. - + {% /property %} - + {% property name="issuerWebsite" type="String" %} The URL of the issuer of the token. - + {% /property %} - + {% property name="issuerImg" type="string" %} The img URL of the issuer that the token belongs to. - + {% /property %} - + {% property name="externalId" type="String" %} The asset identifier from the issuing system. - - + {% /property %} +{% /properties %} --- -## Ledger Model +## Ledger Model {% badge type="experimental" /%} A ledger is a single asset that maintains a balance of multiple tokens belonging to an account. All tokens in a ledger come from a specific collection. Multiple tokens can be spent or sent at once from the ledger. Ledgers have the following attributes along with the base asset fields. - - +{% properties %} + {% property name="collectionId" type="string" %} The [Token Collection](/api/tokens#token-collection-model) that all tokens in the ledger belong to. - + {% /property %} - + {% property name="collectionType" type="string" %} The type of the token collection. - + {% /property %} - + {% property name="tokenValue" type="monetary" %} The value of each token in the ledger. Taken from the `maxValue` property on the token collection. - + {% /property %} - + {% property name="createdBy" type="crn" %} The identity that created the ledger. - + {% /property %} - + {% property name="expiresAt" type="timestamp" %} The date when the ledger expires. - + {% /property %} - + {% property name="balanceExpiresAfter" type="object" %} The active duration of tokens that are issued to this ledger. - + {% /property %} - + {% property name="img" type="string" %} The img URL of the ledger. - + {% /property %} - + {% property name="issuerAccountId" type="string" %} The ID of the Account that issued the tokens in the ledger. - + {% /property %} - + {% property name="balance" type="BigNumber" %} Current number of tokens in the ledger. - + {% /property %} - +{% /properties %} --- - +%} ## Get Asset - +{% /endpoint %} --- - +%} ## Get Asset Summary - +{% /endpoint %} --- - +%} ## List Assets for Account Returns a [paginated](/api/pagination) list of Assets for an account. This will not return archived assets. - - + {% properties %} + {% property name="externalId" type="string" %} The asset identifier from the issuing system. - - - + {% /property %} + {% /properties %} +{% /endpoint %} --- - +%} ## Archive Asset Archive supported asset types by asset id. Currently tokens, and `quartz.nzd` assets may be archived. - - + {% properties heading="Errors" %} + {% error code="403" message="UNSUPPORTED_ASSET_TYPE" %} Asset type can not be archived - - - + {% /error %} + {% /properties %} +{% /endpoint %} --- - +%} ## Get Asset by External Id - +{% /endpoint %} diff --git a/src/content/api/auth.mdx b/src/content/api/auth.mdoc similarity index 95% rename from src/content/api/auth.mdx rename to src/content/api/auth.mdoc index 85d944a9a..36c61d633 100644 --- a/src/content/api/auth.mdx +++ b/src/content/api/auth.mdoc @@ -5,8 +5,6 @@ nav: path: API order: 2 --- -import CodePanel from '../../components/CodePanel.astro'; - ## Authenticating API Calls API calls can be authenticated by either providing an API key in the @@ -17,27 +15,22 @@ Org [Accounts](/api/accounts) 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. - - ```bash title="Authenticate with API key" - curl -X GET https://service.centrapay.com/api/account-memberships \ - -H "X-Api-Key: $api_key" - ``` - - - - ```bash title="Authenticate with user access token" - curl -X GET https://service.centrapay.com/api/account-memberships \ - -H "Authorization: $jwt" - ``` - - - - ```bash title="Authenticate org account with user access token" - curl -X GET https://service.centrapay.com/api/account-memberships \ - -H "Authorization: $jwt" \ - -H "X-Centrapay-Account: Jaim1Cu1Q55uooxSens6yk" - ``` - + +```bash {% title="Authenticate with API key" %} +curl -X GET https://service.centrapay.com/api/account-memberships \ + -H "X-Api-Key: $api_key" +``` + +```bash {% title="Authenticate with user access token" %} +curl -X GET https://service.centrapay.com/api/account-memberships \ + -H "Authorization: $jwt" +``` + +```bash {% title="Authenticate org account with user access token" %} +curl -X GET https://service.centrapay.com/api/account-memberships \ + -H "Authorization: $jwt" \ + -H "X-Centrapay-Account: Jaim1Cu1Q55uooxSens6yk" +``` ## API Keys diff --git a/src/content/api/bank-account-approvals.mdx b/src/content/api/bank-account-approvals.mdoc similarity index 65% rename from src/content/api/bank-account-approvals.mdx rename to src/content/api/bank-account-approvals.mdoc index 628c8a7ca..99f99e822 100644 --- a/src/content/api/bank-account-approvals.mdx +++ b/src/content/api/bank-account-approvals.mdoc @@ -5,12 +5,6 @@ nav: path: Bank Accounts order: 2 --- -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Endpoint from '../../components/Endpoint.astro'; -import Badge from '../../components/Badge.astro'; -import Error from '../../components/Error.astro'; - A Bank Account Approval represents any added authorization on a [Bank Account](/api/bank-accounts). This may be an approval from Centrapay or a consent from a Centrapay [Account](/api/accounts) owner that allows access to a third-party system. See [Bank Account Approval Types](#bank-account-approval-types). @@ -20,59 +14,59 @@ that allows access to a third-party system. See [Bank Account Approval Types](#b ## Bank Account Approval Model - - +{% properties %} + {% property name="id" type="string" %} The Bank Account Approval's unique identifier. - + {% /property %} - + {% property name="bankAccountId" type="string" %} The id of the associated [Bank Account](/api/bank-accounts/). - + {% /property %} - + {% property name="accountId" type="string" %} The id of the owning Centrapay [Account](/api/accounts/). - + {% /property %} - + {% property name="type" type="string" %} The type of Bank Account Approval. See [Bank Account Approval Types](#bank-account-approval-types). - + {% /property %} - + {% property name="status" type="string" %} The current status of the Bank Account Approval. Supported values are `created`, `pending`, `approved`, `declined` and `done`. - + {% /property %} - + {% property name="createdAt" type="timestamp" %} When the Bank Account Approval was created. - + {% /property %} - + {% property name="createdBy" type="crn" %} The User or API Key that created the Bank Account Approval. - + {% /property %} - + {% property name="modifiedAt" type="timestamp" %} When the Bank Account Approval was updated. - + {% /property %} - + {% property name="modifiedBy" type="crn" %} The User or API Key that updated the Bank Account Approval. - + {% /property %} - + {% property name="approvalActivities" type="array" %} An array of [Bank Account Approval Activities](#bank-account-approval-activity-model) associated with the Bank Account Approval. - + {% /property %} - + {% property name="mediaUploadId" type="string" %} The id of the associated [Media Upload](/api/media-uploads). Required for type `settlement`. - + {% /property %} - + {% property name="refreshToken" type="string" %} A long lived access token for access to a third-party system. Required for type `account-information-consent` and `enduring-payment-consent`. - + {% /property %} - + {% property name="consentId" type="string" %} A unique identifier for an authorization in a third-party system. - - + {% /property %} +{% /properties %} ### Bank Account Approval Types @@ -87,123 +81,123 @@ that allows access to a third-party system. See [Bank Account Approval Types](#b ## Bank Account Approval Activity Model - - +{% properties %} + {% property name="activityNumber" type="number" %} Unique sequential Bank Account Approval Activity number. - + {% /property %} - + {% property name="approvalId" type="string" %} The id of the associated [Bank Account Approval](#bank-account-approval-model). - + {% /property %} - + {% property name="activityType" type="string" %} The type of the Bank Account Approval Activity. - + {% /property %} - + {% property name="createdAt" type="timestamp" %} When the Bank Account Approval Activity was created. - + {% /property %} - + {% property name="createdBy" type="crn" %} The User or API Key that created the Bank Account Approval Activity. - - + {% /property %} +{% /properties %} --- - - ## Request Bank Account Approval +%} + ## Request Bank Account Approval {% badge type="experimental" /%} This endpoint allows you to request a Bank Account Approval. - - + {% properties %} + {% property name="mediaUploadId" type="string" required=true %} The id of the associated [Media Upload](/api/media-uploads). - + {% /property %} - + {% property name="bankAccountId" type="string" required=true %} The id of the associated [Bank Account](/api/bank-accounts). - + {% /property %} - + {% property name="type" type="string" required=true %} The [Bank Account Approval Type](#bank-account-approval-types). A Bank Account Approval can only be requested for type `settlement`. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="APPROVAL_ALREADY_IN_PROGRESS" %} There is already a Bank Account Approval in progress that is awaiting review from Centrapay. - - - + {% /error %} + {% /properties %} +{% /endpoint %} --- - - ## Get Bank Account Approval +%} + ## Get Bank Account Approval {% badge type="experimental" /%} This endpoint allows you to retrieve a Bank Account Approval. - +{% /endpoint %} --- - - ## Accept Bank Account Approval +%} + ## Accept Bank Account Approval {% badge type="experimental" /%} This endpoint allows you to accept a Bank Account Approval. - - + {% properties %} + {% property name="reason" type="string" %} The reason for accepting the Bank Account Approval. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="APPROVAL_ALREADY_REVIEWED" %} The Bank Account Approval has already been accepted or declined. - - - + {% /error %} + {% /properties %} +{% /endpoint %} --- - - ## Decline Bank Account Approval +%} + ## Decline Bank Account Approval {% badge type="experimental" /%} This endpoint allows you to decline a Bank Account Approval. - - + {% properties %} + {% property name="reason" type="string" required=true %} The reason for declining the Bank Account Approval. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="APPROVAL_ALREADY_REVIEWED" %} The Bank Account Approval has already been accepted or declined. - - - + {% /error %} + {% /properties %} +{% /endpoint %} --- - - ## List Bank Account Approvals +%} + ## List Bank Account Approvals {% badge type="experimental" /%} This endpoint allows you to list the Bank Account Approvals for a Bank Account. - +{% /endpoint %} diff --git a/src/content/api/bank-account-connection-intents.mdx b/src/content/api/bank-account-connection-intents.mdoc similarity index 67% rename from src/content/api/bank-account-connection-intents.mdx rename to src/content/api/bank-account-connection-intents.mdoc index 36af60d9d..6817e0983 100644 --- a/src/content/api/bank-account-connection-intents.mdx +++ b/src/content/api/bank-account-connection-intents.mdoc @@ -5,63 +5,57 @@ nav: path: Bank Accounts order: 3 --- -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Error from '../../components/Error.astro'; -import Endpoint from '../../components/Endpoint.astro'; -import Badge from '../../components/Badge.astro'; - A Bank Account Connection Intent facilitates user authorization of access to Bank Accounts, for example, using Open Banking flows. Typically the authorization will follow an OAuth flow where the user is redirected to a third-party system to authenticate and select one or more bank accounts. --- ## Bank Account Connection Intent Model - - +{% properties %} + {% property name="id" type="string" %} The Bank Account Connection Intent's unique identifier. - + {% /property %} - + {% property name="accountId" type="string" %} The id of the owning Centrapay [Account](/api/accounts/). - + {% /property %} - + {% property name="type" type="string" %} The type of Bank Account Connection Intent. See [Bank Account Connection Intent Types](#bank-account-connection-intent-types). - + {% /property %} - + {% property name="status" type="string" %} The current status of the Bank Account Connection Intent. Supported values are `created`, `authorized` and `failed`. - + {% /property %} - + {% property name="createdAt" type="timestamp" %} When the Bank Account Connection Intent was created. - + {% /property %} - + {% property name="createdBy" type="crn" %} The User or API Key that created the Bank Account Connection Intent. - + {% /property %} - + {% property name="updatedAt" type="timestamp" %} When the Bank Account Connection Intent was updated. - + {% /property %} - + {% property name="updatedBy" type="crn" %} The User or API Key that updated the Bank Account Connection Intent. - + {% /property %} - + {% property name="authorizationUrl" type="string" %} A URL to the third-party beginning the authorization flow. - + {% /property %} - + {% property name="test" type="boolean" %} A flag which is present if the intention is to connect with a [Bank Account](/api/bank-accounts) used for testing. - + {% /property %} - + {% property name="name" type="string" %} The name of the consent. Only present if type is `enduring-payment-consent`. - - + {% /property %} +{% /properties %} ### Bank Account Connection Intent Types @@ -72,64 +66,64 @@ A Bank Account Connection Intent facilitates user authorization of access to Ban --- - - ## Create Bank Account Connection Intent +%} + ## Create Bank Account Connection Intent {% badge type="experimental" /%} This endpoint allows you to create a Bank Account Connection Intent. - - + {% properties %} + {% property name="accountId" type="string" required=true %} The id of the owning [Account](/api/accounts/). - + {% /property %} - + {% property name="type" type="string" required=true %} The type of Bank Account Connection Intent. - + {% /property %} - + {% property name="bankAccountId" type="string" %} The id of the associated [Bank Account](/api/bank-accounts/). Required if type is `enduring-payment-consent`. - + {% /property %} - + {% property name="test" type="boolean" %} A flag which is present if the intention is to connect with a [Bank Account](/api/bank-accounts/) used for testing. - + {% /property %} - + {% property name="name" type="string" %} The name of the consent. Only available if type is `enduring-payment-consent`. - + {% /property %} - + {% property name="period" type="string" %} The period after which the amount spent using the consent will be reset. Only available if type is `enduring-payment-consent`. Valid values are `daily`, `weekly`, `fortnightly`, `monthly` and `yearly`. Defaults to `daily`. - + {% /property %} - + {% property name="totalAmount" type="string" %} The total cent value of transactions the consent can be used for within the period. Only available if type is `enduring-payment-consent`. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="LIVENESS_MISMATCH" %} Only Bank Account Connection Intents with the `test` flag can be associated with test [Bank Accounts](/api/bank-accounts/), and vice versa. - - - + {% /error %} + {% /properties %} +{% /endpoint %} --- - - ## Authorize Bank Account Connection Intent +%} + ## Authorize Bank Account Connection Intent {% badge type="experimental" /%} This endpoint allows you to authorize a Bank Account Connection Intent. - - + {% properties %} + {% property name="code" type="string" required=true %} Authorization code returned from third-party. - - - + {% /property %} + {% /properties %} +{% /endpoint %} diff --git a/src/content/api/bank-accounts.mdx b/src/content/api/bank-accounts.mdoc similarity index 59% rename from src/content/api/bank-accounts.mdx rename to src/content/api/bank-accounts.mdoc index 682d4947f..4f7fd7220 100644 --- a/src/content/api/bank-accounts.mdx +++ b/src/content/api/bank-accounts.mdoc @@ -5,12 +5,6 @@ nav: path: Bank Accounts order: 1 --- -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Error from '../../components/Error.astro'; -import Endpoint from '../../components/Endpoint.astro'; -import Badge from '../../components/Badge.astro'; - Bank Accounts are used to get money in and out of a Centrapay Account. Money is moved by creating "Top Up" or "Withdrawal" [Funds Transfers](/api/funds-transfers). @@ -22,79 +16,79 @@ bank transaction can be used to verify a bank account. ## Bank Account Model - - +{% properties %} + {% property name="id" type="string" %} The Bank Account's unique identifier. - + {% /property %} - + {% property name="bankAccountNumber" type="string" %} The user's Bank Account number. - + {% /property %} - + {% property name="bankAccountName" type="string" %} The name on the Bank Account provided by the user. - + {% /property %} - + {% property name="preferredBankAccountName" type="string" %} The preferred bank account name for the Bank Account provided by the user. This is only available on Bank Accounts of type [quartz](#bank-account-type). - + {% /property %} - + {% property name="accountId" type="string" %} The id of the owning Centrapay [Account](/api/accounts). - + {% /property %} - + {% property name="status" type="string" %} The current status of the Bank Account. - + {% /property %} - + {% property name="verified" type="boolean" %} Flag indicating the Bank Account is verified, allowing it to be used to Top Up. - + {% /property %} - + {% property name="type" type="string" %} The [Bank Account Type](#bank-account-type) of the bank, defaults to `centrapay`. - + {% /property %} - + {% property name="directDebitAuthority" type="object" %} A [direct-debit authority](#direct-debit-authority-model). By including `directDebitAuthority`, the user accepts our [Direct Debit terms](https://centrapay.com/directdebit-termsandconditions/) and has authority to operate this account. - + {% /property %} - + {% property name="directDebitAuthorized" type="boolean" %} Flag indicating the user accepts our [Direct Debit terms](https://centrapay.com/directdebit-termsandconditions/) and has authority to operate this account. - + {% /property %} - + {% property name="approvals" type="array" %} A list of [Bank Account Approval Type Summaries](#bank-account-approval-type-summary-model). - + {% /property %} - + {% property name="createdAt" type="timestamp" %} When the Bank Account was created. - + {% /property %} - + {% property name="modifiedAt" type="timestamp" %} When the Bank Account was updated. - + {% /property %} - + {% property name="createdBy" type="crn" %} The User or API Key that created the Bank Account. - + {% /property %} - + {% property name="modifiedBy" type="crn" %} The User or API Key that updated the Bank Account. - + {% /property %} - + {% property name="test" type="boolean" %} A flag which is present if the Bank Account is for testing. - + {% /property %} - + {% property name="enduringPaymentConsentAuthorized" type="boolean" %} Flag indicating whether the bank account can be used for creating [enduring payment consents](/api/bank-account-connection-intents#bank-account-connection-intent-types). Only present on [quartz](#bank-account-type) bank accounts. - - + {% /property %} +{% /properties %} -### Bank Account Type +### Bank Account Type {% badge type="experimental" /%} Types of bank accounts to allow access to different [Asset Types](/api/asset-types). @@ -111,67 +105,67 @@ A direct-debit authority is required to be able to Top Up a Bank Account. By inc `directDebitAuthority`, the user accepts our [Direct Debit terms](https://centrapay.com/directdebit-termsandconditions/) and has authority to operate this account. - - +{% properties %} + {% property name="phoneNumber" type="string" %} The user's phone number. - + {% /property %} - + {% property name="fullName" type="string" %} The first and last name of the user. - + {% /property %} - + {% property name="emailAddress" type="string" %} The user's email address. - - + {% /property %} +{% /properties %} --- -## Bank Account Approval Type Summary Model +## Bank Account Approval Type Summary Model {% badge type="experimental" /%} A summary of the [Bank Account Approvals](/api/bank-account-approvals) for a Bank Account. There is one object per type of Bank Account Approval, which provides a summary of the approval status. - - +{% properties %} + {% property name="type" type="string" %} The type of Bank Account Approval Summary. - + {% /property %} - + {% property name="status" type="string" %} The summarized status of the Bank Account Approvals. Supported values are `pending`, `approved` and `declined`. - + {% /property %} - + {% property name="updatedAt" type="timestamp" %} When the Bank Account Approval Summary was updated. - - + {% /property %} +{% /properties %} --- -## Bank Account Balance Model +## Bank Account Balance Model {% badge type="experimental" /%} The Bank Account balance, retrieved using Open Banking flows. The supported Bank Account type is `quartz`. - - +{% properties %} + {% property name="bankAccountId" type="string" %} The unique identifier of the Centrapay Bank Account. - + {% /property %} - + {% property name="balance" type="bignumber" %} The Open Banking Bank Account balance. - + {% /property %} - + {% property name="currency" type="string" %} Currency code (eg. “NZD”). - - + {% /property %} +{% /properties %} --- - +%} ## Create Bank Account A Bank Account can be created with or without direct debit authorized. By including @@ -180,293 +174,293 @@ The Bank Account balance, retrieved using Open Banking flows. The supported Bank `phone`, `fullName` and `emailAddress` are all required to create a direct-debit authority. This is required to be able to Top Up a Bank Account. - - + {% properties %} + {% property name="accountId" type="string" required=true %} The id of the owning Centrapay [Account](/api/accounts). - + {% /property %} - + {% property name="bankAccountNumber" type="string" required=true %} The user's Bank Account number. - + {% /property %} - + {% property name="bankAccountName" type="string" required=true %} The name on the Bank Account provided by the user. - + {% /property %} - + {% property name="directDebitAuthority" type="object" %} A [direct-debit authority](#direct-debit-authority-model). By including `directDebitAuthority`, the user accepts our [Direct Debit terms](https://centrapay.com/directdebit-termsandconditions/) and has authority to operate this account. - + {% /property %} - + {% property name="type" type="string" %} The [Bank Account Type](#bank-account-type) of the bank, defaults to `centrapay`. - + {% /property %} - + {% property name="test" type="boolean" %} A flag which is present if the Bank Account is for testing. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="BANK_ACCOUNT_LIMIT_EXCEEDED" %} The Centrapay account already has the max amount of directDebitAuthorized enabled Bank Accounts. - + {% /error %} - + {% error code="403" message="BANK_ACCOUNT_HOLDER_LIMIT_EXCEEDED" %} The global maximum Bank Accounts for the provided Bank Account number has been reached. - + {% /error %} - + {% error code="403" message="DUPLICATE_BANK_ACCOUNT" %} The Centrapay account already holds this Bank Account. - - - + {% /error %} + {% /properties %} +{% /endpoint %} --- - +%} ## Add Direct Debit Authority to a Bank Account By using this endpoint, the user accepts our [Direct Debit terms](https://centrapay.com/directdebit-termsandconditions/) and has authority to operate this account. - - + {% properties %} + {% property name="phoneNumber" type="string" required=true %} The user's phone number. - + {% /property %} - + {% property name="fullName" type="string" required=true %} The first and last name of the user. - + {% /property %} - + {% property name="emailAddress" type="string" required=true %} The user's email address. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="DIRECT_DEBIT_ALREADY_AUTHORIZED" %} This bank authority cannot be changed as all fields have been set. - + {% /error %} - + {% error code="403" message="DIRECT_DEBIT_LIMIT_EXCEEDED" %} The Centrapay account already has the max amount of directDebitAuthorized enabled Bank Accounts. - - - + {% /error %} + {% /properties %} +{% /endpoint %} --- - +%} ## Get Bank Account This endpoint allows you to retrieve information about a Bank Account. - +{% /endpoint %} --- - - ## Get Bank Account Balance +%} + ## Get Bank Account Balance {% badge type="experimental" /%} This endpoint allows you to retrieve the [balance](#bank-account-balance-model) of a Bank Account. - +{% /endpoint %} --- - +%} ## Verify Bank Account Verification codes show up on statements when a user makes withdrawals and deposits. To verify an account, you need to direct the user to make a Top Up or Withdrawal and then check their statement. - - + {% properties %} + {% property name="verificationCode" type="string" required=true %} The code on the user’s bank statement. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="BANK_ACCOUNT_ALREADY_VERIFIED" %} The bank account is already verified. - + {% /error %} - + {% error code="403" message="VERIFICATION_CODE_INVALID" %} The verification code is incorrect. - + {% /error %} - + {% error code="403" message="BANK_ACCOUNT_VERIFICATION_ATTEMPTS_EXCEEDED" %} The bank account's maximum failed verification attempts has been reached. - + {% /error %} - + {% error code="403" message="ACCOUNT_MISMATCH" %} The top up / withdrawal and the bank account do not belong to the same account. - - - + {% /error %} + {% /properties %} +{% /endpoint %} --- - +%} ## List Bank Accounts This endpoint allows you to list the Bank Accounts for an account. - +{% /endpoint %} --- - +%} ## Set Preferred Bank Account Name - - + {% properties heading="Errors" %} + {% error code="403" message="INVALID_BANK_ACCOUNT_TYPE" %} The type of bank account is not supported for this operation. Only [quartz](#bank-account-type) bank accounts are supported. - - - + {% /error %} + {% /properties %} +{% /endpoint %} --- - +%} ## Archive Bank Account Archives the supplied bank account. This endpoint is currently only supported for `quartz` bank accounts. - +{% /endpoint %} --- - - ## Verify Bank Authority +%} + ## Verify Bank Authority {% badge type="deprecated" /%} If you're creating new interfaces, please work with [Verify Bank Account](#verify-bank-account). - - + {% properties %} + {% property name="verificationCode" type="string" required=true %} The code on the user’s bank statement. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="BANK_ACCOUNT_ALREADY_VERIFIED" %} The bank account is already verified. - + {% /error %} - + {% error code="403" message="VERIFICATION_CODE_INVALID" %} The verification code is incorrect. - + {% /error %} - + {% error code="403" message="BANK_ACCOUNT_VERIFICATION_ATTEMPTS_EXCEEDED" %} The bank account's maximum failed verification attempts has been reached. - + {% /error %} - + {% error code="403" message="ACCOUNT_MISMATCH" %} The top up / withdrawal and the bank account do not belong to the same account. - - - + {% /error %} + {% /properties %} +{% /endpoint %} --- - - ## List Bank Authorities +%} + ## List Bank Authorities {% badge type="deprecated" /%} If you're creating new interfaces, please work with [List Bank Accounts](#list-bank-accounts). - +{% /endpoint %} --- - - ## Create Bank Authority +%} + ## Create Bank Authority {% badge type="deprecated" /%} If you're creating new interfaces, please work with [Create Bank Account](#create-bank-account). Creating a Bank Authority both creates a new Bank Account and a direct debit authority. By using this endpoint, the user accepts our [Direct Debit terms](https://centrapay.com/directdebit-termsandconditions/) and has authority to operate this account. - - + {% properties %} + {% property name="accountId" type="string" required=true %} The id of the owning Centrapay [Account](/api/accounts). - + {% /property %} - + {% property name="fullName" type="string" required=true %} The first and last name of the user. - + {% /property %} - + {% property name="phoneNumber" type="string" required=true %} The user's phone number. - + {% /property %} - + {% property name="emailAddress" type="string" required=true %} The user's email address. - + {% /property %} - + {% property name="bankAccountNumber" type="string" required=true %} The user's Bank Account number. - + {% /property %} - + {% property name="bankAccountName" type="string" required=true %} The name on the Bank Account provided by the user. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="BANK_AUTHORITY_LIMIT_EXCEEDED" %} The account already has the max amount of bank accounts. - + {% /error %} - + {% error code="403" message="BANK_AUTHORITIES_FOR_BANK_ACCOUNT_EXCEEDED" %} There are already two bank accounts for the provided bank account number, which is the maximum allowed. - - - + {% /error %} + {% /properties %} +{% /endpoint %} --- - - ## Get Bank Authority +%} + ## Get Bank Authority {% badge type="deprecated" /%} If you're creating new interfaces, please work with [Get Bank Account](#get-bank-account). - - + {% properties heading="Errors" %} + {% error code="403" message="BANK_AUTHORITY_LIMIT_EXCEEDED" %} The account already has the max amount of bank accounts. - + {% /error %} - + {% error code="403" message="BANK_AUTHORITIES_FOR_BANK_ACCOUNT_EXCEEDED" %} There are already two bank accounts for the provided bank account number, which is the maximum allowed. - - - + {% /error %} + {% /properties %} +{% /endpoint %} diff --git a/src/content/api/batch-types/farmlands-external-asset.mdoc b/src/content/api/batch-types/farmlands-external-asset.mdoc new file mode 100644 index 000000000..49e4cc22a --- /dev/null +++ b/src/content/api/batch-types/farmlands-external-asset.mdoc @@ -0,0 +1,242 @@ +--- +title: Farmlands External Asset Batch +description: Farmlands External Asset Batch Models +nav: + path: Exclude + order: 1 +--- +Loads Farmlands Card data into Centrapay as external assets. + +| Type Name | File Format | Record Type | +| :----------------------- | :------------------------------ | :------------------------ | +| farmlands-external-asset | [JSONL](https://jsonlines.org/) | [Account](#account-model) | + + +## Account Model + +Exported Farmlands Account used for importing and updating of a [Centrapay Asset](/api/assets/). + +{% properties %} + {% property name="externalId" type="string" %} + Id used for keeping imported Centrapay Asset up to date. + {% /property %} + + {% property name="accountNumber" type="string" %} + Farmlands account identifier attached to the Centrapay Asset. + {% /property %} + + {% property name="availableBalance" type="bignumber" %} + Current spendable balance of Centrapay Asset in cents. When not specified, defaults to 0. + {% /property %} + + {% property name="contacts" type="array" %} + [Contact](#contact-model) List for the imported Centrapay Asset. When empty all Contacts are removed. + {% /property %} +{% /properties %} + +--- + +## Contact Model + +Exported Farmlands Contact and [Card](#card-model) information used for authentication, correspondence and payment. + +{% properties %} + {% property name="externalId" type="string" %} + Id used for keeping imported Centrapay Contact details up to date. + {% /property %} + + {% property name="name" type="string" %} + The full name used to address the individual. + {% /property %} + + {% property name="mobile" type="phonenumber" %} + Mobile number used for authentication and correspondence, must start with +64. + {% /property %} + + {% property name="email" type="string" %} + Email address used for authentication and correspondence. + {% /property %} + + {% property name="primary" type="boolean" %} + `true` if the Contact is the owner of the Farmlands Account. + {% /property %} + + {% property name="cards" type="array" %} + [Card](#card-model) list used for payment for the authenticated subject. When empty all Cards are removed. + {% /property %} +{% /properties %} + +--- + +## Card Model + +Exported Farmlands Credit Card information used for importing and updating of a [Patron Code](/api/patron-codes). + +{% properties %} + {% property name="externalId" type="string" %} + Farmlands unique identifier for the card. + {% /property %} + + {% property name="barcode" type="bignumber" %} + Unique 9 digit field to display in barcode format to pay by [Patron Code](/api/patron-codes). + {% /property %} + + {% property name="number" type="PAN" %} + 16 digit primary account number of the Card. + {% /property %} + + {% property name="status" type="string" %} + Current state of the Card. Valid values are "active", "inactive" and "archived". + {% /property %} + + {% property name="expiry" type="timestamp" %} + Payments will be accepted until this time. + {% /property %} + + {% property name="farmlandsStatus" type="string" %} + Private field used in all Farmlands payment transaction notifications. + {% /property %} +{% /properties %} + +--- + +## Example JSONL File + +A complete batch example with all batch types included. For more legible examples please refer to [Example Models](#example-models). + +```json +{"externalId":"9b2ec6d1-c83b-496a-8e52-2989f23d9076","accountNumber":"012345678","availableBalance":"1000","contacts":[]} +{"externalId":"d0d7e14d-4ce5-4f42-8a4c-d604a9609f66","accountNumber":"012345678","availableBalance":"1000"} +{"externalId":"69d64d80-f9bd-4057-bc5b-1c55685d995b","accountNumber":"012345678","contacts":[{"externalId":"6e496c2a-1dae-4036-847d-c53bf6c6d410","name":"Road Runner","mobile":"+64221105598","email":"road@runner.net","primary":true,"cards":[{"externalId":"9b2ec6d1-c83b-496a-8e52-2989f23d9076","barcode":"976238759","number":"1464549137071848","status":"active","expiry":"2022-10-01T22:32:56.631Z"},{"externalId":"74e4f94c-8316-42e7-9aa1-eb1539528894","barcode":"957813964","number":"6583418750394768","status":"inactive","expiry":"2022-08-01T22:32:56.631Z"}]}]} +{"externalId":"b5fde0e0-357c-4fda-a90f-fd857f2be999","accountNumber":"830578479","availableBalance":"12000","contacts":[{"externalId":"6e496c2a-1dae-4036-847d-c53bf6c6d410","name":"Road Runner","mobile":"+64221102598","email":"road@runner.net","primary":true,"cards":[{"externalId":"65e701c3-6973-4322-8fa6-4560a489417f","barcode":"458028560","number":"2072080986444582","status":"active","expiry":"2023-06-01T22:32:56.631Z"},{"externalId":"69d64d80-f9bd-4057-bc5b-1c55685d995b","barcode":"635570865","number":"6982374819924328","status":"inactive","farmlandsStatus":"Suspended by customer","expiry":"2022-04-01T22:32:56.631Z"}]},{"externalId":"6e4813e6-7a18-47ea-b92e-add36c8815ca","name":"Yosemite Sam","mobile":"+64220002598","email":"yosemite@runner.net","primary":false,"cards":[{"externalId":"74e4f94c-8316-42e7-9aa1-eb1539528894","barcode":"137628567","number":"4354969251656341","status":"active","expiry":"2022-04-01T22:32:56.631Z"}]},{"externalId":"82bdb041-ea79-448c-816f-77af8b6750b2","name":"Wile E. Coyote","mobile":"+64221102598","email":"while@e-cyote.net","primary":false,"cards":[{"externalId":"62904b86-b4cc-45a9-b3c9-287a00ae9ef5","barcode":"722798445","number":"5700810476667788","status":"active","expiry":"2022-04-01T22:32:56.631Z"}]}]} +``` + +## Example Models + +Centrapay matches previously created resources using externalId and records get created or updated based on these IDs. In some cases, fields may be omitted to only update some fields. + +> Warning: Below our records have newlines for legibility. When submitting a batch file you must only use newlines to separate records. + +An example of a [Centrapay Asset](/api/assets) complete with availableBalance, contacts and cards. + +```json title="Example Centrapay Asset" +{ + "externalId": "b5fde0e0-357c-4fda-a90f-fd857f2be999", + "accountNumber": "830578479", + "availableBalance": "12000", + "contacts": [ + { + "externalId": "6e496c2a-1dae-4036-847d-c53bf6c6d410", + "name": "Road Runner", + "mobile": "+64221102598", + "email": "road@runner.net", + "primary": true, + "cards": [ + { + "externalId": "65e701c3-6973-4322-8fa6-4560a489417f", + "barcode": "458028560", + "number": "1464549137071848", + "status": "active", + "expiry": "2023-06-01T22:32:56.631Z" + }, + { + "externalId": "69d64d80-f9bd-4057-bc5b-1c55685d995b", + "barcode": "635570865", + "number": "1370718414645498", + "status": "inactive", + "farmlandsStatus": "Suspended by customer", + "expiry": "2022-04-01T22:32:56.631Z" + } + ] + }, + { + "externalId": "6e4813e6-7a18-47ea-b92e-add36c8815ca", + "name": "Yosemite Sam", + "mobile": "+64220002598", + "email": "yosemite@runner.net", + "primary": false, + "cards": [ + { + "externalId": "74e4f94c-8316-42e7-9aa1-eb1539528894", + "barcode": "137628567", + "number": "1364549870718414", + "status": "active", + "expiry": "2022-04-01T22:32:56.631Z" + } + ] + }, + { + "externalId": "82bdb041-ea79-448c-816f-77af8b6750b2", + "name": "Wile E. Coyote", + "mobile": "+64221102598", + "email": "while@e-cyote.net", + "primary": false, + "cards": [ + { + "externalId": "62904b86-b4cc-45a9-b3c9-287a00ae9ef5", + "barcode": "722798445", + "number": "4987071841413645", + "status": "active", + "expiry": "2022-04-01T22:32:56.631Z" + } + ] + } + ] +} +``` + + +Update the availableBalance on an account and remove all contacts associated with it. Note, this renders the availableBalance un-spendable. + +```json +{ + "externalId": "9b2ec6d1-c83b-496a-8e52-2989f23d9076", + "accountNumber": "012345678", + "availableBalance": "1000", + "contacts": [] +} +``` + +Update the availableBalance on an account. + +```json +{ + "externalId": "d0d7e14d-4ce5-4f42-8a4c-d604a9609f66", + "accountNumber": "012345678", + "availableBalance": "1000" +} +``` + +Update the contact list for an account. Use this where you want to exclude availableBalance. + +```json +{ + "externalId": "69d64d80-f9bd-4057-bc5b-1c55685d995b", + "accountNumber": "012345678", + "contacts": [ + { + "externalId": "6e496c2a-1dae-4036-847d-c53bf6c6d410", + "name": "Road Runner", + "mobile": "+64221105598", + "email": "road@runner.net", + "primary": true, + "cards": [ + { + "externalId": "9b2ec6d1-c83b-496a-8e52-2989f23d9076", + "barcode": "976238759", + "number": "0718414498713645", + "status": "active", + "expiry": "2022-10-01T22:32:56.631Z" + }, + { + "externalId": "74e4f94c-8316-42e7-9aa1-eb1539528894", + "barcode": "957813964", + "number": "0714498471364518", + "status": "inactive", + "expiry": "2022-08-01T22:32:56.631Z" + } + ] + } + ] +} +``` diff --git a/src/content/api/batch-types/farmlands-external-asset.mdx b/src/content/api/batch-types/farmlands-external-asset.mdx deleted file mode 100644 index e970f57ea..000000000 --- a/src/content/api/batch-types/farmlands-external-asset.mdx +++ /dev/null @@ -1,256 +0,0 @@ ---- -title: Farmlands External Asset Batch -description: Farmlands External Asset Batch Models -nav: - path: Exclude - order: 1 ---- -import Properties from '../../../components/Properties.astro'; -import Property from '../../../components/Property.astro'; -import CodePanel from '../../../components/CodePanel.astro'; - -Loads Farmlands Card data into Centrapay as external assets. - -| Type Name | File Format | Record Type | -| :----------------------- | :------------------------------ | :------------------------ | -| farmlands-external-asset | [JSONL](https://jsonlines.org/) | [Account](#account-model) | - - -## Account Model - -Exported Farmlands Account used for importing and updating of a [Centrapay Asset](/api/assets/). - - - - Id used for keeping imported Centrapay Asset up to date. - - - - Farmlands account identifier attached to the Centrapay Asset. - - - - Current spendable balance of Centrapay Asset in cents. When not specified, defaults to 0. - - - - [Contact](#contact-model) List for the imported Centrapay Asset. When empty all Contacts are removed. - - - ---- - -## Contact Model - -Exported Farmlands Contact and [Card](#card-model) information used for authentication, correspondence and payment. - - - - Id used for keeping imported Centrapay Contact details up to date. - - - - The full name used to address the individual. - - - - Mobile number used for authentication and correspondence, must start with +64. - - - - Email address used for authentication and correspondence. - - - - `true` if the Contact is the owner of the Farmlands Account. - - - - [Card](#card-model) list used for payment for the authenticated subject. When empty all Cards are removed. - - - ---- - -## Card Model - -Exported Farmlands Credit Card information used for importing and updating of a [Patron Code](/api/patron-codes). - - - - Farmlands unique identifier for the card. - - - - Unique 9 digit field to display in barcode format to pay by [Patron Code](/api/patron-codes). - - - - 16 digit primary account number of the Card. - - - - Current state of the Card. Valid values are "active", "inactive" and "archived". - - - - Payments will be accepted until this time. - - - - Private field used in all Farmlands payment transaction notifications. - - - ---- - -## Example JSONL File - -A complete batch example with all batch types included. For more legible examples please refer to [Example Models](#example-models). - - - ```json title="Example JSONL" - {"externalId":"9b2ec6d1-c83b-496a-8e52-2989f23d9076","accountNumber":"012345678","availableBalance":"1000","contacts":[]} - {"externalId":"d0d7e14d-4ce5-4f42-8a4c-d604a9609f66","accountNumber":"012345678","availableBalance":"1000"} - {"externalId":"69d64d80-f9bd-4057-bc5b-1c55685d995b","accountNumber":"012345678","contacts":[{"externalId":"6e496c2a-1dae-4036-847d-c53bf6c6d410","name":"Road Runner","mobile":"+64221105598","email":"road@runner.net","primary":true,"cards":[{"externalId":"9b2ec6d1-c83b-496a-8e52-2989f23d9076","barcode":"976238759","number":"1464549137071848","status":"active","expiry":"2022-10-01T22:32:56.631Z"},{"externalId":"74e4f94c-8316-42e7-9aa1-eb1539528894","barcode":"957813964","number":"6583418750394768","status":"inactive","expiry":"2022-08-01T22:32:56.631Z"}]}]} - {"externalId":"b5fde0e0-357c-4fda-a90f-fd857f2be999","accountNumber":"830578479","availableBalance":"12000","contacts":[{"externalId":"6e496c2a-1dae-4036-847d-c53bf6c6d410","name":"Road Runner","mobile":"+64221102598","email":"road@runner.net","primary":true,"cards":[{"externalId":"65e701c3-6973-4322-8fa6-4560a489417f","barcode":"458028560","number":"2072080986444582","status":"active","expiry":"2023-06-01T22:32:56.631Z"},{"externalId":"69d64d80-f9bd-4057-bc5b-1c55685d995b","barcode":"635570865","number":"6982374819924328","status":"inactive","farmlandsStatus":"Suspended by customer","expiry":"2022-04-01T22:32:56.631Z"}]},{"externalId":"6e4813e6-7a18-47ea-b92e-add36c8815ca","name":"Yosemite Sam","mobile":"+64220002598","email":"yosemite@runner.net","primary":false,"cards":[{"externalId":"74e4f94c-8316-42e7-9aa1-eb1539528894","barcode":"137628567","number":"4354969251656341","status":"active","expiry":"2022-04-01T22:32:56.631Z"}]},{"externalId":"82bdb041-ea79-448c-816f-77af8b6750b2","name":"Wile E. Coyote","mobile":"+64221102598","email":"while@e-cyote.net","primary":false,"cards":[{"externalId":"62904b86-b4cc-45a9-b3c9-287a00ae9ef5","barcode":"722798445","number":"5700810476667788","status":"active","expiry":"2022-04-01T22:32:56.631Z"}]}]} - ``` - - -## Example Models - -Centrapay matches previously created resources using externalId and records get created or updated based on these IDs. In some cases, fields may be omitted to only update some fields. - -> Warning: Below our records have newlines for legibility. When submitting a batch file you must only use newlines to separate records. - -An example of a [Centrapay Asset](/api/assets) complete with availableBalance, contacts and cards. - - - ```json title="Example Centrapay Asset" - { - "externalId": "b5fde0e0-357c-4fda-a90f-fd857f2be999", - "accountNumber": "830578479", - "availableBalance": "12000", - "contacts": [ - { - "externalId": "6e496c2a-1dae-4036-847d-c53bf6c6d410", - "name": "Road Runner", - "mobile": "+64221102598", - "email": "road@runner.net", - "primary": true, - "cards": [ - { - "externalId": "65e701c3-6973-4322-8fa6-4560a489417f", - "barcode": "458028560", - "number": "1464549137071848", - "status": "active", - "expiry": "2023-06-01T22:32:56.631Z" - }, - { - "externalId": "69d64d80-f9bd-4057-bc5b-1c55685d995b", - "barcode": "635570865", - "number": "1370718414645498", - "status": "inactive", - "farmlandsStatus": "Suspended by customer", - "expiry": "2022-04-01T22:32:56.631Z" - } - ] - }, - { - "externalId": "6e4813e6-7a18-47ea-b92e-add36c8815ca", - "name": "Yosemite Sam", - "mobile": "+64220002598", - "email": "yosemite@runner.net", - "primary": false, - "cards": [ - { - "externalId": "74e4f94c-8316-42e7-9aa1-eb1539528894", - "barcode": "137628567", - "number": "1364549870718414", - "status": "active", - "expiry": "2022-04-01T22:32:56.631Z" - } - ] - }, - { - "externalId": "82bdb041-ea79-448c-816f-77af8b6750b2", - "name": "Wile E. Coyote", - "mobile": "+64221102598", - "email": "while@e-cyote.net", - "primary": false, - "cards": [ - { - "externalId": "62904b86-b4cc-45a9-b3c9-287a00ae9ef5", - "barcode": "722798445", - "number": "4987071841413645", - "status": "active", - "expiry": "2022-04-01T22:32:56.631Z" - } - ] - } - ] - } - ``` - - - -Update the availableBalance on an account and remove all contacts associated with it. Note, this renders the availableBalance un-spendable. - - - ```json title="Example Centrapay Asset" - { - "externalId": "9b2ec6d1-c83b-496a-8e52-2989f23d9076", - "accountNumber": "012345678", - "availableBalance": "1000", - "contacts": [] - } - ``` - - -Update the availableBalance on an account. - - - ```json title="Example Centrapay Asset" - { - "externalId": "d0d7e14d-4ce5-4f42-8a4c-d604a9609f66", - "accountNumber": "012345678", - "availableBalance": "1000" - } - ``` - - -Update the contact list for an account. Use this where you want to exclude availableBalance. - - - ```json title="Example Centrapay Asset" - { - "externalId": "69d64d80-f9bd-4057-bc5b-1c55685d995b", - "accountNumber": "012345678", - "contacts": [ - { - "externalId": "6e496c2a-1dae-4036-847d-c53bf6c6d410", - "name": "Road Runner", - "mobile": "+64221105598", - "email": "road@runner.net", - "primary": true, - "cards": [ - { - "externalId": "9b2ec6d1-c83b-496a-8e52-2989f23d9076", - "barcode": "976238759", - "number": "0718414498713645", - "status": "active", - "expiry": "2022-10-01T22:32:56.631Z" - }, - { - "externalId": "74e4f94c-8316-42e7-9aa1-eb1539528894", - "barcode": "957813964", - "number": "0714498471364518", - "status": "inactive", - "expiry": "2022-08-01T22:32:56.631Z" - } - ] - } - ] - } - ``` - diff --git a/src/content/api/batch-types/ticketek-ticket.mdoc b/src/content/api/batch-types/ticketek-ticket.mdoc new file mode 100644 index 000000000..b424886d5 --- /dev/null +++ b/src/content/api/batch-types/ticketek-ticket.mdoc @@ -0,0 +1,53 @@ +--- +title: Ticketek Ticket Batch +description: Ticketek Ticket Batch Models +nav: + path: Exclude + order: 1 +--- +Loads Ticketek tickets into Centrapay as Patron codes and tokens. + +| Type Name | File Format | Record Type | +| :-------------- | :------------------------------ | :---------------- | +| ticketek-ticket | [JSONL](https://jsonlines.org/) | [Ticket Sale](#ticket-sale) | + +## Ticket Sale + +{% properties %} + {% property name="barcodeClear" type="string" %} + The barcode number of the ticket. + {% /property %} + + {% property name="quantity" type="number" %} + "1" for a purchase and "-1" for a cancellation. + {% /property %} + + {% property name="priceTypeCode" type="string" %} + Code for the price type of the product for the sale. + {% /property %} + + {% property name="productId" type="string" %} + Unique identifier for the product of the sale. + {% /property %} + + {% property name="orderId" type="string" %} + Unique identifier for the sale. + {% /property %} + + {% property name="priceTypeName" type="string" %} + Descriptive for the price type of the product for the sale. + {% /property %} + + {% property name="memberNumber" type="string" %} + Native identifier for a member of an organisation. + {% /property %} +{% /properties %} + +--- + +## Example JSONL File + +```json +{"quantity": 1, "priceTypeCode": "J", "productId": "ABCD12345", "orderId": "20231206,886", "priceTypeName": "Renewing Member", "memberNumber": "1111", "barcodeClear": "12398542"} +{"quantity": -1, "priceTypeCode": "J", "productId": "ABCD12345", "orderId": "20231206,886", "priceTypeName": "Renewing Junior", "barcodeClear": "1783379123"} +``` diff --git a/src/content/api/batch-types/ticketek-ticket.mdx b/src/content/api/batch-types/ticketek-ticket.mdx deleted file mode 100644 index 1afc03572..000000000 --- a/src/content/api/batch-types/ticketek-ticket.mdx +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Ticketek Ticket Batch -description: Ticketek Ticket Batch Models -nav: - path: Exclude - order: 1 ---- -import Properties from '../../../components/Properties.astro'; -import Property from '../../../components/Property.astro'; -import CodePanel from '../../../components/CodePanel.astro'; - -Loads Ticketek tickets into Centrapay as Patron codes and tokens. - -| Type Name | File Format | Record Type | -| :-------------- | :------------------------------ | :---------------- | -| ticketek-ticket | [JSONL](https://jsonlines.org/) | [Ticket Sale](#ticket-sale) | - -## Ticket Sale - - - - The barcode number of the ticket. - - - - "1" for a purchase and "-1" for a cancellation. - - - - Code for the price type of the product for the sale. - - - - Unique identifier for the product of the sale. - - - - Unique identifier for the sale. - - - - Descriptive for the price type of the product for the sale. - - - - Native identifier for a member of an organisation. - - - ---- - -## Example JSONL File - - - ```json title="Example JSONL" - {"quantity": 1, "priceTypeCode": "J", "productId": "ABCD12345", "orderId": "20231206,886", "priceTypeName": "Renewing Member", "memberNumber": "1111", "barcodeClear": "12398542"} - {"quantity": -1, "priceTypeCode": "J", "productId": "ABCD12345", "orderId": "20231206,886", "priceTypeName": "Renewing Junior", "barcodeClear": "1783379123"} - ``` - diff --git a/src/content/api/batch-types/verifone-terminal-status.mdoc b/src/content/api/batch-types/verifone-terminal-status.mdoc new file mode 100644 index 000000000..6999e5de4 --- /dev/null +++ b/src/content/api/batch-types/verifone-terminal-status.mdoc @@ -0,0 +1,112 @@ +--- +title: Verifone Terminal Status Batch +description: Verifone Terminal Status Batch Models +nav: + path: Exclude + order: 1 +--- +Performs a bulk update to the current status for connected Verifone NZ payment terminals. See the [Batch](/api/batches) resource for how to submit an instance of this batch. + +| Type Name | File Format | Record Type | +| :----------------------- | :------------------------------ | :---------------------------------- | +| verifone-terminal-status | [JSONL](https://jsonlines.org/) | [Terminal Status](#terminal-status) | + +## Terminal Status + +{% properties %} + {% property name="status" type="string" %} + Current terminal status: "active" or "inactive". + {% /property %} + + {% property name="statusMessage" type="string" %} + Reason for status. Eg: "config update required". + {% /property %} + + {% property name="terminalId" type="string" %} + Logical terminal id. Eg: "325-136-329". + {% /property %} + + {% property name="deviceId" type="string" %} + Hardware serial number. Eg: "T404395000002". + {% /property %} + + {% property name="merchantId" type="string" %} + Centrapay [Merchant](/api/merchants) id. + {% /property %} + + {% property name="merchantConfigId" type="string" %} + Centrapay [Merchant Config](/api/merchant-configs) id. + {% /property %} + + {% property name="merchantName" type="string" %} + Name of merchant. Eg: "Centra Café". + {% /property %} + + {% property name="description" type="string" %} + Description of the device. Eg "Front Till". + {% /property %} + + {% property name="model" type="string" %} + Hardware model. Eg: "VX820". + {% /property %} + + {% property name="firstSeen" type="timestamp" %} + Date when terminal status was first observed. + {% /property %} + + {% property name="lastSeen" type="timestamp" %} + Date when terminal status was last observed. + {% /property %} + + {% property name="configVersion" type="string" %} + Version of loaded terminal configuration. Eg: "20220214.1". + {% /property %} + + {% property name="configUpdatedAt" type="timestamp" %} + Date when terminal configuration was loaded. + {% /property %} + + {% property name="softwareVersion" type="string" %} + Version of terminal software. Eg: "1.7.134". + {% /property %} + + {% property name="softwareUpdatedAt" type="timestamp" %} + Date when terminal software was updated. + {% /property %} +{% /properties %} + +--- + +## Example JSONL File + +A complete batch example with all batch types included. For more legible examples please refer to [Example Models](#pretty-printed-example). + +```json +{"merchantId":"06baa0708ee0e000696","merchantConfigId":"baa09e8158300063fc","merchantName":"Centra Café","description":"Till #1","model":"VX820","terminalId":"325-136-331","deviceId":"T404395000004","status":"inactive","statusMessage":"update required","firstSeen":"2020-01-14T09:00:00Z","lastSeen":"2022-03-14T09:00:00Z","configVersion": 20210914.1,"configUpdatedAt":"2021-09-15 09:00:00 UTC","softwareVersion":"1.7.134","softwareUpdatedAt":"2021-11-14 09:00:00 UTC"} +{"merchantId":"06baa0708ee0e000696","merchantConfigId":"baa09e8158300063fc","merchantName":"Centra Café","description":"Till #2","model":"VX820","terminalId":"325-136-329","deviceId":"T404395000002","status":"active","statusMessage":"ok","firstSeen":"2020-01-14T09:00:00Z","lastSeen":"2022-03-14T09:00:00Z","configVersion": 20220214.1,"configUpdatedAt":"2022-02-14 09:00:00 UTC","softwareVersion":"1.7.134","softwareUpdatedAt":"2021-11-14 09:00:00 UTC"} +``` +--- + +## Pretty Printed Example + +> Below our records have newlines for legibility. When submitting a batch file you must only use newlines to separate records. + +```json +{ + "merchantId": "06baa0708ee0e000696", + "merchantConfigId": "baa09e8158300063fc", + "merchantName": "Centra Café", + "description": "Till #2", + "model": "VX820", + "terminalId": "325-136-329", + "deviceId": "T404395000002", + "status": "active", + "statusMessage": "incompatible hardware", + "firstSeen": "2020-01-14T09:00:00Z", + "lastSeen": "2022-03-14T09:00:00Z", + "configVersion": 20220214.1, + "configUpdatedAt": "2022-02-14 09:00:00 UTC", + "softwareVersion": "1.7.134", + "softwareUpdatedAt": "2021-11-14 09:00:00 UTC" +} +``` diff --git a/src/content/api/batch-types/verifone-terminal-status.mdx b/src/content/api/batch-types/verifone-terminal-status.mdx deleted file mode 100644 index a1ae468bc..000000000 --- a/src/content/api/batch-types/verifone-terminal-status.mdx +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: Verifone Terminal Status Batch -description: Verifone Terminal Status Batch Models -nav: - path: Exclude - order: 1 ---- -import Properties from '../../../components/Properties.astro'; -import Property from '../../../components/Property.astro'; -import CodePanel from '../../../components/CodePanel.astro'; - -Performs a bulk update to the current status for connected Verifone NZ payment terminals. See the [Batch](/api/batches) resource for how to submit an instance of this batch. - -| Type Name | File Format | Record Type | -| :----------------------- | :------------------------------ | :---------------------------------- | -| verifone-terminal-status | [JSONL](https://jsonlines.org/) | [Terminal Status](#terminal-status) | - -## Terminal Status - - - - Current terminal status: "active" or "inactive". - - - - Reason for status. Eg: "config update required". - - - - Logical terminal id. Eg: "325-136-329". - - - - Hardware serial number. Eg: "T404395000002". - - - - Centrapay [Merchant](/api/merchants) id. - - - - Centrapay [Merchant Config](/api/merchant-configs) id. - - - - Name of merchant. Eg: "Centra Café". - - - - Description of the device. Eg "Front Till". - - - - Hardware model. Eg: "VX820". - - - - Date when terminal status was first observed. - - - - Date when terminal status was last observed. - - - - Version of loaded terminal configuration. Eg: "20220214.1". - - - - Date when terminal configuration was loaded. - - - - Version of terminal software. Eg: "1.7.134". - - - - Date when terminal software was updated. - - - ---- - -## Example JSONL File - -A complete batch example with all batch types included. For more legible examples please refer to [Example Models](#pretty-printed-example). - - - ```json title="Example JSONL" - {"merchantId":"06baa0708ee0e000696","merchantConfigId":"baa09e8158300063fc","merchantName":"Centra Café","description":"Till #1","model":"VX820","terminalId":"325-136-331","deviceId":"T404395000004","status":"inactive","statusMessage":"update required","firstSeen":"2020-01-14T09:00:00Z","lastSeen":"2022-03-14T09:00:00Z","configVersion": 20210914.1,"configUpdatedAt":"2021-09-15 09:00:00 UTC","softwareVersion":"1.7.134","softwareUpdatedAt":"2021-11-14 09:00:00 UTC"} - {"merchantId":"06baa0708ee0e000696","merchantConfigId":"baa09e8158300063fc","merchantName":"Centra Café","description":"Till #2","model":"VX820","terminalId":"325-136-329","deviceId":"T404395000002","status":"active","statusMessage":"ok","firstSeen":"2020-01-14T09:00:00Z","lastSeen":"2022-03-14T09:00:00Z","configVersion": 20220214.1,"configUpdatedAt":"2022-02-14 09:00:00 UTC","softwareVersion":"1.7.134","softwareUpdatedAt":"2021-11-14 09:00:00 UTC"} - ``` - - ---- - -## Pretty Printed Example - -> Below our records have newlines for legibility. When submitting a batch file you must only use newlines to separate records. - - - ```json title="Example" - { - "merchantId": "06baa0708ee0e000696", - "merchantConfigId": "baa09e8158300063fc", - "merchantName": "Centra Café", - "description": "Till #2", - "model": "VX820", - "terminalId": "325-136-329", - "deviceId": "T404395000002", - "status": "active", - "statusMessage": "incompatible hardware", - "firstSeen": "2020-01-14T09:00:00Z", - "lastSeen": "2022-03-14T09:00:00Z", - "configVersion": 20220214.1, - "configUpdatedAt": "2022-02-14 09:00:00 UTC", - "softwareVersion": "1.7.134", - "softwareUpdatedAt": "2021-11-14 09:00:00 UTC" - } - ``` - diff --git a/src/content/api/batches.mdx b/src/content/api/batches.mdoc similarity index 72% rename from src/content/api/batches.mdx rename to src/content/api/batches.mdoc index f7cdfd0c9..52aed75a9 100644 --- a/src/content/api/batches.mdx +++ b/src/content/api/batches.mdoc @@ -5,47 +5,41 @@ nav: path: API order: 10 --- - -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Error from '../../components/Error.astro'; -import Endpoint from '../../components/Endpoint.astro'; - Batches enable bulk loading of resource onto the Centrapay platform. ## Batch Model - - +{% properties %} + {% property name="id" type="string" %} The Batch's unique identifier. - + {% /property %} - + {% property name="status" type="string" %} The current [Lifecycle Stage](#batch-lifecycle) of the batch. - + {% /property %} - + {% property name="type" type="string" %} [Batch Type](#batch-types) id used to describe the batch content. - + {% /property %} - + {% property name="totalCount" type="bignumber" %} The number of items processed. - + {% /property %} - + {% property name="errorCount" type="bignumber" %} Total [Error](#error) counted. - + {% /property %} - + {% property name="errors" type="array" %} [Error](#error) list for the batch. - + {% /property %} - + {% property name="test" type="boolean" %} true if the batch is for testing purposes only. - + {% /property %} - +{% /properties %} ### Batch Lifecycle @@ -81,46 +75,46 @@ The following table describes the Batch Types supported for loading. --- - +%} ## Create Batch Initialize loading of entities from a batch file. - - + {% properties %} + {% property name="type" type="string" required=true %} [Batch Type](#batch-types) used to describe the batch content. - + {% /property %} - + {% property name="url" type="string" required=true %} The url where the file is located. - + {% /property %} - + {% property name="accountId" type="string" required=true %} Centrapay Account Id that submitted the Batch. - + {% /property %} - + {% property name="test" type="boolean" %} true if the batch is for testing purposes only. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="LIVENESS_MISMATCH" %} accountId `test` flag is not the same as submitted Batch’s `test` flag. - - - + {% /error %} + {% /properties %} +{% /endpoint %} --- - +%} ## Get Batch This endpoint allows you to retrieve a Batch by id. - +{% /endpoint %} diff --git a/src/content/api/businesses.mdx b/src/content/api/businesses.mdoc similarity index 67% rename from src/content/api/businesses.mdx rename to src/content/api/businesses.mdoc index 41582685a..b14aa5b31 100644 --- a/src/content/api/businesses.mdx +++ b/src/content/api/businesses.mdoc @@ -5,74 +5,68 @@ nav: path: Accounts order: 3 --- -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Error from '../../components/Error.astro'; -import Endpoint from '../../components/Endpoint.astro'; -import Badge from '../../components/Badge.astro'; - A Business represents a company registered with the New Zealand Companies Office. It is associated with a single [Account](/api/accounts). ## Business Model - - +{% properties %} + {% property name="id" type="string" %} The unique identifier. - + {% /property %} - + {% property name="accountId" type="string" %} The Centrapay accountId for an org account. - + {% /property %} - + {% property name="accountName" type="string" %} The Centrapay account name for an org account. - + {% /property %} - + {% property name="nzbn" type="string" %} The unique NZBN identifier. - + {% /property %} - + {% property name="name" type="string" %} Legal name recorded in the Companies Register. - + {% /property %} - + {% property name="tradingName" type="string" %} Trading name recorded in the Companies Register. - + {% /property %} - + {% property name="companyNumber" type="string" %} Company number recorded in the Companies Register. - + {% /property %} - + {% property name="createdAt" type="timestamp" %} When the Business was created. - + {% /property %} - + {% property name="updatedAt" type="timestamp" %} When the Business was updated. - + {% /property %} - + {% property name="createdBy" type="crn" %} The User or API Key that created the Business. - + {% /property %} - + {% property name="updatedBy" type="crn" %} The User or API Key that updated the Business. - + {% /property %} - + {% property name="taxNumber" type="object" %} The value-added tax configuration for the Business. See [Tax Number Model](#tax-number-model). - + {% /property %} - + {% property name="onboardingStatus" type="crn" %} The onboarding status of the Business. See [Onboarding Statuses](#onboarding-statuses) for possible values. - + {% /property %} - + {% property name="onboardingStatusReason" type="string" %} The reason associated with the [Onboarding Status](#onboarding-statuses). See [Onboarding Status Reasons](#onboarding-status-reasons) for possible values. - - + {% /property %} +{% /properties %} ### Onboarding Statuses @@ -100,140 +94,140 @@ A Business represents a company registered with the New Zealand Companies Office ## Tax Number Model - - +{% properties %} + {% property name="value" type="string" %} The tax number. - + {% /property %} - + {% property name="type" type="string" %} Type of value-added tax. Can be `nz-gst`. - - + {% /property %} +{% /properties %} --- - - ## Create Business +%} + ## Create Business {% badge type="experimental" /%} This endpoint allows you to create a new Business. If `accountId` is not provided when creating a Business, then a new org account will be created and associated to the Business. - - + {% properties %} + {% property name="nzbn" type="string" required=true %} The unique NZBN identifier. - + {% /property %} - + {% property name="accountId" type="string" %} The Centrapay accountId. - + {% /property %} - + {% property name="test" type="string" %} The created Centrapay org account will have the test flag. - + {% /property %} - + {% property name="taxNumber" type="object" %} The value-added tax configuration. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="INVALID_ACCOUNT" %} Account does not exist, is not authorized, is of the wrong type, or is not in the NZ region. - + {% /error %} - + {% error code="403" message="INVALID_NZBN" %} The NZBN provided does not match any NZ business. - + {% /error %} - + {% error code="403" message="BUSINESS_ALREADY_EXISTS" %} The account already has a business or there is already a business with the provided NZBN. - - - + {% /error %} + {% /properties %} +{% /endpoint %} --- - - ## Update Business +%} + ## Update Business {% badge type="experimental" /%} This endpoint allows you to update a Business. - - + {% properties %} + {% property name="tradingName" type="string" %} The trading name of the business. - + {% /property %} - + {% property name="taxNumber" type="object" %} The value-added tax configuration. - + {% /property %} - + {% property name="farmlandsBusinessNumber" type="string" %} The number associated with your Farmlands business. - - - + {% /property %} + {% /properties %} +{% /endpoint %} --- - - ## Get Business by Account Id +%} + ## Get Business by Account Id {% badge type="experimental" /%} This endpoint allows you to retrieve a Business by account id. - +{% /endpoint %} --- - - ## Search NZ Company Register +%} + ## Search NZ Company Register {% badge type="experimental" /%} This endpoint returns a list of companies that match the queried param on company name, nzbn number or company number. Results are [paginated](/api/pagination) and ordered by relevance. - +{% /endpoint %} --- - - ## Get Business Details from NZ Company Register +%} + ## Get Business Details from NZ Company Register {% badge type="experimental" /%} This endpoint allows you to retrieve a Business by account id. - +{% /endpoint %} --- - +%} ## Set Business Onboarding Status This endpoint returns allows you to set the [onboarding status](#onboarding-statuses) of a Business. - - + {% properties %} + {% property name="onboardingStatus" type="crn" %} The onboarding status of the Business. See [Onboarding Statuses](#onboarding-statuses) for possible values. - + {% /property %} - + {% property name="onboardingStatusReason" type="string" %} The reason associated with the [Onboarding Status](#onboarding-statuses). See [Onboarding Status Reasons](#onboarding-status-reasons) for possible values. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="BUSINESS_ALREADY_EXISTS" %} The account already has a business or there is already a business with the provided NZBN. - - - + {% /error %} + {% /properties %} +{% /endpoint %} diff --git a/src/content/api/centrapay-event-types.mdx b/src/content/api/centrapay-event-types.mdoc similarity index 100% rename from src/content/api/centrapay-event-types.mdx rename to src/content/api/centrapay-event-types.mdoc diff --git a/src/content/api/data-types.mdx b/src/content/api/data-types.mdoc similarity index 100% rename from src/content/api/data-types.mdx rename to src/content/api/data-types.mdoc diff --git a/src/content/api/events.mdoc b/src/content/api/events.mdoc new file mode 100644 index 000000000..d25c37249 --- /dev/null +++ b/src/content/api/events.mdoc @@ -0,0 +1,39 @@ +--- +title: Events +description: Events and related endpoints +nav: + path: Events + order: 1 +--- +An event is a record of a user action or outcome. Centrapay performs various tasks in response to events. + +--- + +{% endpoint + path="/api/accounts/{accountId}/events" + filename="events-create" +%} + ## Create Event {% badge type="experimental" /%} + + This endpoint allows you to create an [Event](/api/events). + + {% properties %} + {% property name="type" type="string" required=true %} + The type of Event. + {% /property %} + + {% property name="idempotencyKey" type="string" required=true %} + Client-supplied identifier that prevents double creation. + {% /property %} + + {% property name="data" type="object" %} + An object containing any relevant metadata. + {% /property %} + {% /properties %} + + {% properties heading="Errors" %} + {% error code="403" message="EVENT_ALREADY_EXISTS" %} + An Event with this `idempotencyKey` has already been created for the account. + {% /error %} + {% /properties %} +{% /endpoint %} diff --git a/src/content/api/events.mdx b/src/content/api/events.mdx deleted file mode 100644 index 6ed47d287..000000000 --- a/src/content/api/events.mdx +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Events -description: Events and related endpoints -nav: - path: Events - order: 1 ---- -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Error from '../../components/Error.astro'; -import Endpoint from '../../components/Endpoint.astro'; -import Badge from '../../components/Badge.astro'; - -An event is a record of a user action or outcome. Centrapay performs various tasks in response to events. - ---- - - - ## Create Event - - This endpoint allows you to create an [ Event ](/api/events). - - - - The type of Event. - - - - Client-supplied identifier that prevents double creation. - - - - An object containing any relevant metadata. - - - - - - An Event with this `idempotencyKey` has already been created for the account. - - - diff --git a/src/content/api/funds-transfers.mdx b/src/content/api/funds-transfers.mdoc similarity index 56% rename from src/content/api/funds-transfers.mdx rename to src/content/api/funds-transfers.mdoc index 70a8e5b09..e023b463a 100644 --- a/src/content/api/funds-transfers.mdx +++ b/src/content/api/funds-transfers.mdoc @@ -5,150 +5,143 @@ nav: path: Bank Accounts order: 4 --- - -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Error from '../../components/Error.astro'; -import Endpoint from '../../components/Endpoint.astro'; -import Badge from '../../components/Badge.astro'; - A funds transfer represents either a top up to or a withdrawal from a Centrapay wallet. Topping up a wallet consists of making a bank transfer from the user's bank account to Centrapay. Once Centrapay has verified the transfer was successful a user will be given credit on their Centrapay wallet equal to the amount of the bank transfer. --- - +%} ## Get Top Up This endpoint allows you to retrieve a Top Up by id. - +{% /endpoint %} --- - +%} ## List Top Ups For Authorized Accounts This endpoint allows you to list the Top Ups for authorized accounts. - +{% /endpoint %} --- - - ## List Top Ups For an Account +%} + ## List Top Ups For an Account {% badge type="experimental" /%} This endpoint allows you to list the Top Ups for an account. - +{% /endpoint %} --- - - ## Create Withdrawal +%} + ## Create Withdrawal {% badge type="experimental" /%} This endpoint allows you to create a withdrawal. - - + {% properties %} + {% property name="amount" type="bignumber" required=true %} Total amount of the transaction in cents - + {% /property %} - + {% property name="assetId" type="string" required=true %} The id of the asset - + {% /property %} - + {% property name="bankAccountId" type="string" required=true %} The id of the bank account - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="BANK_AUTHORITY_WALLET_MISMATCH" %} The wallet and the bank account for the withdrawal request do not belong to the same account. - + {% /error %} - - The wallet balance is less than the required amount. - + {% error code="403" message="INSUFFICIENT_WALLET_BALANCE" %} + The wallet balance is less than the required=true amount. + {% /error %} - + {% error code="403" message="INVALID_WALLET_TYPE" %} The wallet type does not support withdrawals. See [settlement wallets](/api/wallets#settlement-wallets). - + {% /error %} - + {% error code="403" message="BANK_ACCOUNT_TYPE_NOT_CONFIGURED_FOR_WITHDRAWAL" %} The bank account type is not configured for withdrawals. Only `centrapay` type bank accounts are configured. - - - + {% /error %} + {% /properties %} +{% /endpoint %} --- - - ## Get Withdrawal +%} + ## Get Withdrawal {% badge type="experimental" /%} This endpoint allows you to retrieve a Withdrawal by id. - - + {% properties heading="Errors" %} + {% error code="403" message="BANK_AUTHORITY_WALLET_MISMATCH" %} The wallet and the bank account for the withdrawal request do not belong to the same account. - + {% /error %} - + {% error code="403" message="INSUFFICIENT_WALLET_BALANCE" %} The wallet balance is less than the required amount. - + {% /error %} - + {% error code="403" message="INVALID_WALLET_TYPE" %} The wallet type does not support withdrawals. See [settlement wallets](/api/wallets#settlement-wallets). - + {% /error %} - + {% error code="403" message="BANK_ACCOUNT_TYPE_NOT_CONFIGURED_FOR_WITHDRAWAL" %} The bank account type is not configured for withdrawals. Only `centrapay` type bank accounts are configured. - - - + {% /error %} + {% /properties %} +{% /endpoint %} --- - - ## List Withdrawals for an Account +%} + ## List Withdrawals for an Account {% badge type="experimental" /%} This endpoint allows you to list the withdrawals for an Account. - +{% /endpoint %} --- - +%} ## Abort Funds Transfer This endpoint allows you to abort a Funds Transfer. - - + {% properties heading="Errors" %} + {% error code="403" message="ABORT_WITHDRAWAL_NOT_SUPPORTED" %} Aborting funds transfers of type `withdrawal` is not supported. - + {% /error %} - + {% error code="403" message="FUNDS_TRANSFER_ALREADY_COMPLETE" %} The funds transfer is already complete. - - - + {% /error %} + {% /properties %} +{% /endpoint %} diff --git a/src/content/api/http-status-codes.mdx b/src/content/api/http-status-codes.mdoc similarity index 79% rename from src/content/api/http-status-codes.mdx rename to src/content/api/http-status-codes.mdoc index 6a567a915..bc8c705dc 100644 --- a/src/content/api/http-status-codes.mdx +++ b/src/content/api/http-status-codes.mdoc @@ -5,8 +5,6 @@ nav: path: API order: 3 --- -import CodePanel from '../../components/CodePanel.astro'; - Centrapay APIs respond with 200, 400, 401, 403, 404, or 429 HTTP status codes. In rare cases endpoints may respond with 5xx status codes. @@ -24,14 +22,12 @@ behaves in order to get back the resource that you're after. Don't try again, this is never going to work. - - ```json title="Response" - { - "statusCode": 400, - "message": "amount is required" - } - ``` - +```json +{ + "statusCode": 400, + "message": "amount is required" +} +``` ### Debugging * Make sure you set "content-type: application/json". @@ -46,15 +42,13 @@ Don't try again, this is never going to work. API key or JWT is missing, expired or invalid. Go look at our [Auth](/api/auth) documentation. - - ```json title="Response" - { - "statusCode": 401, - "error": "Unauthorized", - "message": "Missing authentication" - } - ``` - +```json +{ + "statusCode": 401, + "error": "Unauthorized", + "message": "Missing authentication" +} +``` ## 403 Forbidden @@ -63,14 +57,12 @@ business rule violation. ### Resource missing or permission denied - - ```json title="Response" - "statusCode": 403, - "error": "Forbidden", - "message": "Forbidden" - } - ``` - +```json + "statusCode": 403, + "error": "Forbidden", + "message": "Forbidden" +} +``` * Check the resource id is correct * Check your user or API key has membership for the account that owns the resource you are accessing. @@ -83,44 +75,38 @@ is violated then a 403 is returned. Additional information will be included in the "message" field of the response body. The possible values for the "message" field will be documented on each endpoint. - - ```json title="Response" - { - "statusCode": 403, - "error": "Forbidden", - "message": "INSUFFICIENT_BALANCE" - } - ``` - +```json +{ + "statusCode": 403, + "error": "Forbidden", + "message": "INSUFFICIENT_BALANCE" +} +``` ## 404 Route Not Found Variant on a 400, there's a bug in your code that means you've got a typo in the URL or HTTP method. Please check against examples in our documentation. - -```json title="Response" +```json { "statusCode": 404, "error": "Not Found", "message": "Not Found" } ``` - ## 429 Too Many Requests Centrapay API rate limits have been exceeded. - -```json title="Response" +```json { "statusCode": 429, "error": "Too Many Requests", "message": "RATE_LIMIT_EXCEEDED" } ``` - ### Debugging * Check the `Retry-After` HTTP response header for the number of seconds diff --git a/src/content/api/integration-requests.mdx b/src/content/api/integration-requests.mdoc similarity index 60% rename from src/content/api/integration-requests.mdx rename to src/content/api/integration-requests.mdoc index b74011f67..82ea24e82 100644 --- a/src/content/api/integration-requests.mdx +++ b/src/content/api/integration-requests.mdoc @@ -5,95 +5,89 @@ nav: path: Integrations order: 2 --- -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Error from '../../components/Error.astro'; -import Endpoint from '../../components/Endpoint.astro'; -import Badge from '../../components/Badge.astro'; - An Integration Request allows Centrapay users to request the creation of an [Integration](/api/integrations/) on a Centrapay Account. ## Integration Request Model - - +{% properties %} + {% property name="id" type="string" %} The unique identifier of the Integration Request. - + {% /property %} - + {% property name="accountId" type="string" %} The Integration Request's owning Centrapay [Account](/api/accounts/) id. - + {% /property %} - + {% property name="merchantId" type="string" %} The [Merchant](/api/merchants) id for the Integration Request. - + {% /property %} - + {% property name="type" type="object" %} The type of the Integration Request. Refer to [Integration Types](#integration-types). - + {% /property %} - + {% property name="status" type="string" %} The current status of the Integration Request. Supported values are `active`, `available`, `pending`, `rejected` and `disabled`. - + {% /property %} - + {% property name="terminalId" type="string" %} Epay terminalId for the Integration Request. Required if type is `epay`. - + {% /property %} - + {% property name="terminal" type="object" %} The terminal configuration. Required for all terminal vendors except Vista. Refer to [Terminal](#terminal). - + {% /property %} - + {% property name="product" type="object" %} The requested Epay gift card types to support. Refer to [Product](#product). - + {% /property %} - + {% property name="createdAt" type="timestamp" %} When the Integration Request was created. - + {% /property %} - + {% property name="createdBy" type="crn" %} The User or API Key that created the Integration Request. - + {% /property %} - + {% property name="updatedAt" type="timestamp" %} When the Integration Request was updated. - + {% /property %} - + {% property name="updatedBy" type="crn" %} The User or API Key that updated the Integration Request. - + {% /property %} - + {% property name="notifiedAt" type="timestamp" %} When the Integration Request was submitted to the terminal provider in order to enable the terminal for Centrapay acceptance. - + {% /property %} - + {% property name="externalId" type="string" %} The external identifier for the integration. Required for `shopify` integration requests. - - + {% /property %} +{% /properties %} ### Terminal - - +{% properties %} + {% property name="terminalId" type="string" %} The software or logical id of the payment terminal. - - + {% /property %} + {% property name="deviceId" type="string" %} The hardware id or serial number of the payment terminal. - - + {% /property %} +{% /properties %} --- ### Product - - +{% properties %} + {% property name="name" type="string" %} The name of the requested Epay product. - - + {% /property %} +{% /properties %} ### Integration Types @@ -110,131 +104,131 @@ An Integration Request allows Centrapay users to request the creation of an [Int --- - - ## Create an Integration Request +%} + ## Create an Integration Request {% badge type="experimental" /%} This endpoint allows you to create an Integration Request. - - + {% properties %} + {% property name="merchantId" type="string" required=true %} The [Merchant](/api/merchants) id for the Integration Request. - + {% /property %} - + {% property name="type" type="object" required=true %} The type of the Integration Request. Refer to [Integration Types](#integration-types). - + {% /property %} - + {% property name="terminal" type="object" %} The terminal configuration. Required for all terminal vendors except Vista. Refer to [Terminal](#terminal). - + {% /property %} - + {% property name="product" type="object" %} The requested Epay gift card types to support. Refer to [Product](#product). - + {% /property %} - + {% property name="externalId" type="string" %} The external identifier for the integration. Required for `shopify` integration requests. - - - + {% /property %} + {% /properties %} +{% /endpoint %} --- - - ## Get an Integration Request + %} + ## Get an Integration Request {% badge type="experimental" /%} This endpoint allows you to get an Integration Request. - +{% /endpoint %} --- - +%} ## Search Integration Requests Returns a [paginated](/api/pagination/) response of Integration Requests. ### Query Parameters - - + {% properties %} + {% property name="accountId" type="string" %} The Integration Request's owning Centrapay Account id. Required unless caller has global read access permission. - + {% /property %} - + {% property name="type" type="string" %} The type of Integration Request. - + {% /property %} - + {% property name="pending" type="boolean" %} When set to `true`, only include Integration Requests with pending status. - - - + {% /property %} + {% /properties %} +{% /endpoint %} --- - - ## Configure Integration Request +%} + ## Configure Integration Request {% badge type="experimental" /%} This endpoint allows you to supply configuration values for the Integration Request. - - + {% properties %} + {% property name="terminalId" type="string" %} Epay terminalId for the Integration Request. Required if type is `epay`. - - - + {% /property %} + {% /properties %} +{% /endpoint %} --- - - ## Get Integration Request Configuration +%} + ## Get Integration Request Configuration {% badge type="experimental" /%} This endpoint allows you to get the configuration values for the Integration Request. - +{% /endpoint %} --- - - ## Activate Integration Request +%} + ## Activate Integration Request {% badge type="experimental" /%} This endpoint allows you to activate an Integration Request. - - - Integration Request needs updating with the required parameters before activating. - + {% properties heading="Errors" %} + {% error code="403" message="INTEGRATION_PARAM_MISSING" %} + Integration Request needs updating with the parameters before activating. + {% /error %} - + {% error code="403" message="INTEGRATION_ALREADY_ACTIVATED" %} Integration Request is already activated. - - + {% /error %} + {% /properties %} - +{% /endpoint %} --- - - ## Delete Integration Request +%} + ## Delete Integration Request {% badge type="experimental" /%} This endpoint allows you to delete an Integration Request. - +{% /endpoint %} diff --git a/src/content/api/integrations.mdx b/src/content/api/integrations.mdoc similarity index 100% rename from src/content/api/integrations.mdx rename to src/content/api/integrations.mdoc diff --git a/src/content/api/introduction.mdx b/src/content/api/introduction.mdoc similarity index 82% rename from src/content/api/introduction.mdx rename to src/content/api/introduction.mdoc index 0e90ef360..f4639d8e3 100644 --- a/src/content/api/introduction.mdx +++ b/src/content/api/introduction.mdoc @@ -5,9 +5,6 @@ nav: path: API order: 1 --- - -import Badge from '../../components/Badge.astro'; - The Centrapay API is an [RMM](https://en.wikipedia.org/wiki/Richardson_Maturity_Model) level 2 RESTful web service which expresses operations in terms of HTTP verbs on resource-oriented URLs. API endpoint definitions in these docs are grouped by resource @@ -17,7 +14,7 @@ Most API calls require [authentication](/api/auth) using an API key or JWT. HTTP requests and responses usually have JSON payloads and use "application/json" as the content type. -Some API features may be flagged as . These API features may be +Some API features may be flagged as {% badge type="experimental" /%}. These API features may be removed or changed without warning and should not be relied on in a production setting. diff --git a/src/content/api/invitations.mdoc b/src/content/api/invitations.mdoc new file mode 100644 index 000000000..6d470e3e0 --- /dev/null +++ b/src/content/api/invitations.mdoc @@ -0,0 +1,225 @@ +--- +title: Invitations +description: Invitation model and related endpoints +nav: + path: API + order: 13 +--- +An Invitation can be used to allow users to claim ownership of a resource on the Centrapay platform. + +## Invitation Model + + +{% properties %} + {% property name="id" type="string" %} + The Invitation's unique identifier. + {% /property %} + + {% property name="code" type="string" %} + The Invitation code. + {% /property %} + + {% property name="type" type="string" %} + The type of invitation. Supported values are `account-membership`. + {% /property %} + + {% property name="resourceId" type="string" %} + The id of the related resource. + {% /property %} + + {% property name="resourceType" type="string" %} + The type of the related resource. Supported values are `account`. + {% /property %} + + {% property name="expiresAt" type="timestamp" %} + When the Invitation expires. + {% /property %} + + {% property name="createdAt" type="timestamp" %} + When the Invitation was created. + {% /property %} + + {% property name="createdBy" type="crn" %} + The User or API Key that created the Invitation. + {% /property %} + + {% property name="updatedAt" type="timestamp" %} + When the Invitation was updated. + {% /property %} + + {% property name="updatedBy" type="crn" %} + The User or API Key that updated the Invitation. + {% /property %} + + {% property name="accepted" type="boolean" %} + A flag indicating whether the Invitation has been accepted. + {% /property %} + + {% property name="acceptedAt" type="timestamp" %} + When the Invitation was accepted. + {% /property %} + + {% property name="acceptedBy" type="crn" %} + The User or API Key that accepted the Invitation. + {% /property %} + + {% property name="acceptedByAccountId" type="string" %} + The [Account](/api/accounts) id of the user accepting the Invitation. + {% /property %} + + {% property name="recipientAlias" type="string" %} + The email address of the user accepting the Invitation. + {% /property %} + + {% property name="params" type="object" %} + [Params](#params-model) dependent on the Invitation type. + {% /property %} + + {% property name="status" type="string" %} + The status of the invitation. Possible values are `created`, `sent`, `accepted` and `revoked`. + {% /property %} +{% /properties %} + +--- + +## Params Model + + +{% properties %} + {% property name="role" type="string" %} + The role assigned to the recipient, for invitations of type `account-membership`. + {% /property %} + + {% property name="accountName" type="string" %} + The name of the account that the recipient is invited to, for invitations of type `account-membership` + {% /property %} +{% /properties %} + +--- + +{% endpoint + path="/api/invitations" + filename="invitations-create" +%} + ## Create Invitation {% badge type="experimental" /%} + + This endpoint allows you to create an Invitation. + + {% properties %} + {% property name="type" type="string" required=true %} + The type of invitation. Supported values are `account-membership`. + {% /property %} + + {% property name="resourceId" type="string" required=true %} + The id of the related resource. + {% /property %} + + {% property name="resourceType" type="string" required=true %} + The type of the related resource. Supported values are `account`. + {% /property %} + + {% property name="recipientAlias" type="string" required=true %} + The email address of the user accepting the Invitation. + {% /property %} + + {% property name="params" type="object" required=true %} + [Params](#params-model) depending on the Invitation type. + {% /property %} + + {% property name="role" type="string" required=true %} + The role that will be assigned to the user when the Invitation is accepted. + {% /property %} + {% /properties %} + + {% properties heading="Errors" %} + {% error code="403" message="INVALID_ACCOUNT_TYPE" %} + The resourceId is associated with an account with a non `org` type. + {% /error %} + + {% error code="403" message="RECIPIENT_ALREADY_INVITED" %} + An active invitation for this recipientAlias and resource already exists, or the recipient has already joined the resource. + {% /error %} + {% /properties %} +{% /endpoint %} + +--- + +{% endpoint + path="/api/invitations/code/{code}" + filename="invitations-get-by-code" +%} + ## Get Invitation By Code {% badge type="experimental" /%} + + This endpoint allows you to retrieve an Invitation by code. +{% /endpoint %} + +--- + +{% endpoint + path="/api/accounts/{accountId}/invitations" + filename="invitations-list-by-accountId" +%} + ## List Invitations by Account Id {% badge type="experimental" /%} + + This endpoint allows you list Invitations for an Account. +{% /endpoint %} + +--- + +{% endpoint + path="/api/invitations/{invitationId}/accept" + filename="invitations-accept" +%} + ## Accept Invitation {% badge type="experimental" /%} + + This endpoint allows you to accept an Invitation. + + {% properties %} + {% property name="code" type="string" required=true %} + The Invitation code. + {% /property %} + + {% property name="accountId" type="string" required=true %} + The [Account](/api/accounts) id of the user accepting the Invitation. + {% /property %} + {% /properties %} + + {% properties heading="Errors" %} + {% error code="403" message="INVITATION_EXPIRED" %} + The Invitation is expired. + {% /error %} + + {% error code="403" message="INVITATION_ALREADY_ACCEPTED" %} + The Invitation has already been accepted. + {% /error %} + + {% error code="403" message="RECIPIENT_ALIAS_MISMATCH" %} + The alias of the user accepting an Invitation is not the same as the recipientAlias of the Invitation. + {% /error %} + + {% error code="403" message="INVITATION_REVOKED" %} + The Invitation was revoked. + {% /error %} + {% /properties %} +{% /endpoint %} + +--- + +{% endpoint + path="/api/invitations/{invitationId}/revoke" + filename="invitations-revoke" +%} + ## Revoke Invitation {% badge type="experimental" /%} + + This endpoint allows you to revoke an Invitation. + + {% properties heading="Errors" %} + {% error code="403" message="INVITATION_EXPIRED" %} + The Invitation is expired. + {% /error %} + + {% error code="403" message="INVITATION_ACCEPTED" %} + The Invitation has already been accepted. + {% /error %} + {% /properties %} +{% /endpoint %} diff --git a/src/content/api/invitations.mdx b/src/content/api/invitations.mdx deleted file mode 100644 index 3cd34a2f3..000000000 --- a/src/content/api/invitations.mdx +++ /dev/null @@ -1,231 +0,0 @@ ---- -title: Invitations -description: Invitation model and related endpoints -nav: - path: API - order: 13 ---- -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Error from '../../components/Error.astro'; -import Endpoint from '../../components/Endpoint.astro'; -import Badge from '../../components/Badge.astro'; - -An Invitation can be used to allow users to claim ownership of a resource on the Centrapay platform. - -## Invitation Model - - - - - The Invitation's unique identifier. - - - - The Invitation code. - - - - The type of invitation. Supported values are `account-membership`. - - - - The id of the related resource. - - - - The type of the related resource. Supported values are `account`. - - - - When the Invitation expires. - - - - When the Invitation was created. - - - - The User or API Key that created the Invitation. - - - - When the Invitation was updated. - - - - The User or API Key that updated the Invitation. - - - - A flag indicating whether the Invitation has been accepted. - - - - When the Invitation was accepted. - - - - The User or API Key that accepted the Invitation. - - - - The [Account](/api/accounts) id of the user accepting the Invitation. - - - - The email address of the user accepting the Invitation. - - - - [Params](#params-model) dependent on the Invitation type. - - - - The status of the invitation. Possible values are `created`, `sent`, `accepted` and `revoked`. - - - ---- - -## Params Model - - - - - The role assigned to the recipient, for invitations of type `account-membership`. - - - - The name of the account that the recipient is invited to, for invitations of type `account-membership` - - - ---- - - - ## Create Invitation - - This endpoint allows you to create an Invitation. - - - - The type of invitation. Supported values are `account-membership`. - - - - The id of the related resource. - - - - The type of the related resource. Supported values are `account`. - - - - The email address of the user accepting the Invitation. - - - - [Params](#params-model) depending on the Invitation type. - - - - The role that will be assigned to the user when the Invitation is accepted. - - - - - - The resourceId is associated with an account with a non `org` type. - - - - An active invitation for this recipientAlias and resource already exists, or the recipient has already joined the resource. - - - - ---- - - - ## Get Invitation By Code - - This endpoint allows you to retrieve an Invitation by code. - - ---- - - - ## List Invitations by Account Id - - This endpoint allows you list Invitations for an Account. - - ---- - - - ## Accept Invitation - - This endpoint allows you to accept an Invitation. - - - - The Invitation code. - - - - The [Account](/api/accounts) id of the user accepting the Invitation. - - - - - - The Invitation is expired. - - - - The Invitation has already been accepted. - - - - The alias of the user accepting an Invitation is not the same as the recipientAlias of the Invitation. - - - - The Invitation was revoked. - - - - ---- - - - ## Revoke Invitation - - This endpoint allows you to revoke an Invitation. - - - - The Invitation is expired. - - - - The Invitation has already been accepted. - - - diff --git a/src/content/api/legacy-payment-requests.mdx b/src/content/api/legacy-payment-requests.mdoc similarity index 67% rename from src/content/api/legacy-payment-requests.mdx rename to src/content/api/legacy-payment-requests.mdoc index 48d370fcf..9cc5ce38e 100644 --- a/src/content/api/legacy-payment-requests.mdx +++ b/src/content/api/legacy-payment-requests.mdoc @@ -5,127 +5,119 @@ nav: path: Payment Requests order: 2 --- - -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Error from '../../components/Error.astro'; -import Endpoint from '../../components/Endpoint.astro'; -import Badge from '../../components/Badge.astro'; -import CodePanel from '../../components/CodePanel.astro'; - Centrapay Payment Requests are serviced via two sets of endpoints; the "next" version (documented [Payment Requests](/api/payment-requests)) and the "legacy" version -(documented on this page). These endpoints are . +(documented on this page). These endpoints are {% badge type="deprecated" /%}. > Use of legacy endpoints for new integrations is discouraged where alternative endpoints have been provided. --- -## Payment Request Model +## Payment Request Model {% badge type="deprecated" /%} - - +{% properties %} + {% property name="requestId" type="string" %} The ID of the Payment Request. - - + {% /property %} + {% property name="merchantId" type="string" %} The ID of the Merchant creating the request. - - + {% /property %} + {% property name="merchantName" type="string" %} The name of the Merchant the Payment Request is on behalf of. - - + {% /property %} + {% property name="clientId" type="string" %} The ID of the merchant specific client configuration. - - + {% /property %} + {% property name="denomination" type="monetary" %} The value of the Payment Request. - - + {% /property %} + {% property name="payments" type="array" %} The [Legacy Payment Options](#payment-options-model) - - + {% /property %} + {% property name="qrCode" type="string" %} The URL for a Centrapay webpage that allows the user to pay the Payment Request. - - + {% /property %} + {% property name="requestCode" type="string" %} The URL for a Centrapay webpage that allows the user to pay the Payment Request. - - + {% /property %} + {% property name="patronCode" type="string" %} The id of a [Patron Code](/api/patron-codes) the payment request is attached to. - - + {% /property %} + {% property name="status" type="string" %} `new`, `paid`, `cancelled`, or `expired`. - - + {% /property %} + {% property name="cancellationReason" type="string" %} The [Cancellation Reason](/api/payment-requests#cancellation-reasons). - - + {% /property %} + {% property name="createdAt" type="timestamp" %} When the Payment Request was created. - - + {% /property %} + {% property name="updatedAt" type="timestamp" %} When the Payment Request was updated. - - + {% /property %} + {% property name="liveness" type="string" %} Indicates liveness of assets that are accepted, determined by the payment options. Values are `main` or `test`. - - + {% /property %} + {% property name="paymentExpirySeconds" type="string" %} The expiry seconds used to configure the Payment Request expiry. - - + {% /property %} + {% property name="terminalId" type="string" %} The software or logical id of the payment terminal. - - + {% /property %} + {% property name="deviceId" type="string" %} The hardware id or serial number of the payment terminal. - - + {% /property %} + {% property name="description" type="string" %} A human readable description of the payment. - - + {% /property %} + {% property name="externalReference" type="string" %} An external reference to the Payment Request. - - + {% /property %} + {% property name="paidBy" type="string" %} The payment details. See [Paid By](#paid-by-model). - - + {% /property %} + {% property name="shortCode" type="string" %} A shorter id that can be used to identify the Payment Request for up to two years. - - + {% /property %} + {% property name="notifyUrl" type="string" %} The URL that will receive the webhook POST requests. - - + {% /property %} +{% /properties %} --- -## Payment Options Model +## Payment Options Model {% badge type="deprecated" /%} - - +{% properties %} + {% property name="ledger" type="string" %} Related to the [Asset Type](/api/asset-types) for the payment. See [ledger and authorization values](#ledger-and-authorization-values). - - + {% /property %} + {% property name="amount" type="number" %} The amount in the minimum divisible units of the denominated asset that would satisfy the payment. - - + {% /property %} + {% property name="account" type="string" %} The Centrapay Account which the payment should be made to. - - + {% /property %} + {% property name="methods" type="string" %} A collection of methods indicating how the payment can be carried out. Valid values: `qr_code`. - - + {% /property %} +{% /properties %} --- -## Paid By Model +## Paid By Model {% badge type="deprecated" /%} - - +{% properties %} + {% property name="transactionId" type="string" %} The transaction to refund. The transaction id for a payment can be obtained from a webhook notification or from [requests.info](#get-a-payment-request). - - + {% /property %} + {% property name="amount" type="number" %} The amount paid. - - + {% /property %} +{% /properties %} --- @@ -148,207 +140,207 @@ is returned with the payment request info as `payments[].ledger`. --- - - ## Create a Payment Request +%} + ## Create a Payment Request {% badge type="deprecated" /%} This endpoint allows you to create a Payment Request. - - + {% properties %} + {% property name="amount" type="number" required=true %} The amount in the minimum divisible units of the denominated asset that would satisfy the payment. - - + {% /property %} + {% property name="asset" type="string" required=true %} The [Asset Type](/api/asset-types) for the payment. - - + {% /property %} + {% property name="merchantId" type="string" required=true %} The ID of the Merchant creating the request. - - + {% /property %} + {% property name="clientId" type="string" %} The ID of the merchant specific client configuration. - - + {% /property %} + {% property name="description" type="string" %} A human readable description of the payment. - - + {% /property %} + {% property name="externalReference" type="string" %} An external reference to the Payment Request. - - + {% /property %} + {% property name="notifyUrl" type="string" %} The URL that will receive the webhook POST requests. - - + {% /property %} + {% property name="patronCode" type="string" %} The id of a [Patron Code](/api/patron-codes) the payment request is attached to. - - + {% /property %} + {% property name="paymentExpirySeconds" type="string" %} The expiry seconds used to configure the Payment Request expiry. - - + {% /property %} + {% property name="terminalId" type="string" %} The software or logical id of the payment terminal. - - + {% /property %} + {% property name="deviceId" type="string" %} The hardware id or serial number of the payment terminal. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="400" message="CHECKSUM_FAILED" %} `patronCode` luhn checksum digit doesn’t pass. - - + {% /error %} + {% error code="403" message="PATRON_CODE_INVALID" %} `patronCode` doesn’t exist or has expired. - - + {% /error %} + {% error code="403" message="MERCHANT_CONFIGURATION_NOT_FOUND" %} There was no merchant configuration found for the supplied merchantId and clientId. - - + {% /error %} + {% error code="403" message="NO_AVAILABLE_PAYMENT_OPTIONS" %} No payment options match the requested payment parameters. - - + {% /error %} + {% /properties %} - +{% /endpoint %} --- - - ## Get a Payment Request +%} + ## Get a Payment Request {% badge type="deprecated" /%} This endpoint allows you to receive Payment Request information. - - + {% properties %} + {% property name="requestId" type="string" required=true %} The payment requestId that is generated when [requests.create](#create-a-payment-request) is called. - - - + {% /property %} + {% /properties %} +{% /endpoint %} --- - - ## Pay a Payment Request +%} + ## Pay a Payment Request <{% badge type="deprecated" /%} This endpoint allows you to pay a Payment Request. - - + {% properties %} + {% property name="requestId" type="string" required=true %} The payment requestId that is generated when [requests.create](#create-a-payment-request) is called. - - + {% /property %} + {% property name="ledger" type="string" required=true %} Relates to the [Asset Type](/api/asset-types) for the payment. See [ledger and authorization values](#ledger-and-authorization-values) for expected values. - - + {% /property %} + {% property name="authorization" type="string" required=true %} An identifier that can be used to pay or verify payment. See [ledger and authorization values](#ledger-and-authorization-values) for expected values. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="REQUEST_EXPIRED" %} Action cannot be completed because the request has expired. - - + {% /error %} + {% error code="403" message="REQUEST_PAID" %} Action cannot be completed because the request has been paid. - - + {% /error %} + {% error code="403" message="REQUEST_CANCELLED" %} Action cannot be completed because the request has already been cancelled. - - + {% /error %} + {% error code="403" message="INVALID_ASSET_TYPE" %} The merchant is not configured with the provided asset type. - - + {% /error %} + {% error code="403" message="INACTIVE_ASSET" %} The asset is not spendable. It may have been disabled, expired, or already spent. - - + {% /error %} + {% error code="403" message="INVALID_MERCHANT_CONFIG" %} The merchant is not configured properly to satisfy the payment request. This could be due to incorrect information, or the merchant’s credentials might be blocked by an external service. - - + {% /error %} + {% error code="403" message="QUOTA_EXCEEDED" %} The payment pay request exceeds the allowed spend quota supplied. - - + {% /error %} + {% error code="403" message="INSUFFICIENT_ASSET_VALUE" %} The asset has insufficient funds to pay the payment request or the transaction amount received by Centrapay is less than the total of the payment. - - + {% /error %} + {% error code="403" message="ASSET_REDEMPTION_DENIED" %} The asset redemption has been unsuccessful due to an error with provided payment parameters, the merchant, or the asset. - - + {% /error %} + {% /properties %} - +{% /endpoint %} --- - - ## Cancel a Payment Request +%} + ## Cancel a Payment Request {% badge type="deprecated" /%} This endpoint allows you to cancel a Payment Request. - - + {% properties %} + {% property name="requestId" type="string" required=true %} The payment requestId that is generated when [requests.create](#create-a-payment-request) is called. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="400" message="REQUEST_NOT_FOUND" %} The provided request doesn’t exist. - - + {% /error %} + {% error code="400" message="REQUEST_EXPIRED" %} Action cannot be completed because the request has expired. - - + {% /error %} + {% error code="404" message="REQUEST_PAID" %} Action cannot be completed because the request has been paid. - - + {% /error %} + {% /properties %} - +{% /endpoint %} --- - - ## Void a Payment Request +%} + ## Void a Payment Request {% badge type="deprecated" /%} This endpoint allows you to void a Payment Request. - - + {% properties %} + {% property name="requestId" type="string" required=true %} The payment requestId that is generated when [requests.create](#create-a-payment-request) is called. - - + {% /property %} + {% /properties %} - + {% properties heading="Errors" %} Voiding a payment request can cause it to be cancelled or refunded. Therefore, this endpoint can give the same error responses as [requests.cancel](#cancel-a-payment-request) and [transactions.refund](#refund-a-transaction). After 24 hours voiding a payment request will be disallowed, however a refund can still be made against the payment request if it has been paid successfully. - + {% error code="400" message="REQUEST_NOT_FOUND" %} The provided request doesn’t exist. - - + {% /error %} + {% error code="400" message="REQUEST_EXPIRED" %} Action cannot be completed because the request has expired. - - + {% /error %} + {% error code="404" message="REQUEST_PAID" %} Action cannot be completed because the request has been paid. - - + {% /error %} + {% /properties %} - +{% /endpoint %} --- - - ## Refund a Transaction +%} + ## Refund a Transaction {% badge type="deprecated" /%} Refunding a transaction can be done with or without an external reference. @@ -373,52 +365,52 @@ is returned with the payment request info as `payments[].ledger`. The legacy refund endpoint cannot be used to refund Pre Auth Payment Requests with Confirmations. Please use the [current refund endpoint](/api/payment-requests#refund-a-payment-request) instead. - - + {% properties %} + {% property name="transactionId" type="string" required=true %} The transaction to refund. The transaction id for a payment can be obtained from a webhook notification or from [requests.info](#get-a-payment-request). - - + {% /property %} + {% property name="amount" type="string" required=true %} The amount to refund in cents. - - + {% /property %} + {% property name="externalReference" type="string" %} A reference supplied by the merchant that must be unique for each refund of that transaction, can be anything you want but it must be unique. - - + {% /property %} + {% /properties %} ### Errors - - + {% properties %} + {% error code="400" message="ALREADY_REFUNDED" %} The transaction has already been refunded. - - + {% /error %} + {% error code="400" message="INVALID_AMOUNT" %} The refund requested is greater than the transaction amount. - - + {% /error %} + {% error code="400" message="REPEAT_REFERENCE" %} A separate refund request for the same transaction has the same external reference, trying to refund the same transaction twice with the same external reference is not allowed. If the amount of the refund is the same we assume it is a repeat request and return 200. - - + {% /error %} + {% error code="403" message="PARTIAL_REFUNDS_NOT_ALLOWED" %} The asset does not support partial refunds. - - + {% /error %} + {% error code="403" message="INACTIVE_ASSET" %} The asset is not refundable. It may have been disabled, expired, or already refunded. - - + {% /error %} + {% error code="403" message="REFUND_NOT_SUPPORTED" %} The asset type does not support refunds. - - + {% /error %} + {% error code="403" message="REFUND_WINDOW_EXCEEDED" %} The time since the payment exceeds the window of time a transaction can be refunded in. - - + {% /error %} + {% error code="403" message="REFUND_DECLINED" %} The refund parameters were valid but refund was declined because additional business rules were violated. - - + {% /error %} + {% /properties %} - +{% /endpoint %} --- -## Webhooks +## Webhooks {% badge type="deprecated" /%} Webhook notifications are sent for significant Payment life-cycle events. The Webhook endpoint is notified by sending an HTTP POST request to the @@ -477,13 +469,12 @@ below but with `transactionType` set to REFUND. The body of the webhook is a JSON document with the following format: - - ```json - { - "token": "${JWT}" - } - ``` - + +```json +{ + "token": "${JWT}" +} +``` The decoded JWT will contain a `transaction` property with a `transactionType` @@ -491,22 +482,20 @@ that indicates the event type. Depending on the type of event, the payload will also contain additional details about the transaction and payment request. For example: - - ```json - { - "transaction": { - "transactionType": "REFUND", - "request": { - "requestId": "bec358bf-edb5-4633-a785-a95cc281d3b7", - "denomination": { - "asset": "NZD", - "amount": "100" - } +```json +{ + "transaction": { + "transactionType": "REFUND", + "request": { + "requestId": "bec358bf-edb5-4633-a785-a95cc281d3b7", + "denomination": { + "asset": "NZD", + "amount": "100" } } } - ``` - +} +``` #### Webhook Payload Fields @@ -528,19 +517,16 @@ example: A webhook JWT can be validated by checking the signature against the Centrapay Webhook public key: - ``` -----BEGIN PUBLIC KEY----- MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEt+vW2fE0mLLmdzJtYrz7J9q/yEXl gmIjCXdv3VNvYfTsaBO5PJNiaD3l9lD8PzEQu31ePsOG81mDVuo40+dgLg== -----END PUBLIC KEY----- ``` - ### Decoded Webhook JWT Examples - -```json title="Transaction Completed Successfully" +```json {% title="Transaction Completed Successfully" %} { "transaction": { "transactionId": "E6ctbmgmkgZ3xnPk3BkGvb", @@ -561,10 +547,8 @@ gmIjCXdv3VNvYfTsaBO5PJNiaD3l9lD8PzEQu31ePsOG81mDVuo40+dgLg== } } ``` - - -```json title="Payment Request Cancelled" +```json {% title="Payment Request Cancelled" %} { "transaction": { "transactionType": "CANCELLED", @@ -580,4 +564,3 @@ gmIjCXdv3VNvYfTsaBO5PJNiaD3l9lD8PzEQu31ePsOG81mDVuo40+dgLg== } } ``` - diff --git a/src/content/api/loyalty-program-memberships.mdoc b/src/content/api/loyalty-program-memberships.mdoc new file mode 100644 index 000000000..a23ad9471 --- /dev/null +++ b/src/content/api/loyalty-program-memberships.mdoc @@ -0,0 +1,83 @@ +--- +title: Loyalty Program Memberships +description: Loyalty Program Memberships model and related endpoints +nav: + path: Loyalty Programs + order: 2 +--- +A Loyalty Program Membership represents an Account's membership to a Loyalty Program. + +## Loyalty Program Membership Model + +{% properties %} + {% property name="id" type="string" %} + The unique identifier of the Loyalty Program Membership. + {% /property %} + + {% property name="accountId" type="string" %} + The [Account](/api/accounts/) that is being onboarded to the Loyalty Program. + {% /property %} + + {% property name="programId" type="string" %} + The id of the Loyalty Program that the Membership is created for. + {% /property %} + + {% property name="name" type="string" %} + The display name of the Loyalty Program. + {% /property %} + + {% property name="description" type="string" %} + The displayable description for the Loyalty Program. + {% /property %} + + {% property name="status" type="string" %} + The status of the Loyalty Program Membership. + {% /property %} + + {% property name="mediaUploadId" type="string" %} + The id of the [Media Upload](/api/media-uploads/) image of the Loyalty Program. + {% /property %} + + {% property name="img" type="string" %} + The img URL of the Loyalty Program. + {% /property %} + + {% property name="createdAt" type="timestamp" %} + When the Loyalty Program Membership was created. + {% /property %} + + {% property name="createdBy" type="crn" %} + The User or API Key that created the Loyalty Program Membership. + {% /property %} + + {% property name="test" type="boolean" %} + `true` if the Loyalty Program Membership is for testing purposes only. + {% /property %} +{% /properties %} + +--- + +{% endpoint + path="/api/loyalty-programs/{loyaltyProgramId}/memberships" + filename="loyalty-program-memberships-create" +%} + ## Create Loyalty Program Memberships {% badge type="experimental" /%} + + This endpoint allows you to create [Loyalty Program Memberships](#loyalty-program-membership-model) to onboard users to [Loyalty Programs](#loyalty-program-model). + + {% properties %} + {% property name="accountId" type="string" required=true %} + The [Account](/api/accounts/) that is being onboarded to the Loyalty Program. + {% /property %} + {% /properties %} + + {% properties heading="Errors" %} + {% error code="403" message="MEMBERSHIP_ALREADY_EXISTS" %} + A membership has already been created for this account and this loyalty program. + {% /error %} + + {% error code="403" message="LOYALTY_PROGRAM_ACCOUNT_LIVENESS_MISMATCH" %} + The account cannot be test if the loyalty program is not test. + {% /error %} + {% /properties %} +{% /endpoint %} diff --git a/src/content/api/loyalty-program-memberships.mdx b/src/content/api/loyalty-program-memberships.mdx deleted file mode 100644 index 49f5adfa2..000000000 --- a/src/content/api/loyalty-program-memberships.mdx +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: Loyalty Program Memberships -description: Loyalty Program Memberships model and related endpoints -nav: - path: Loyalty Programs - order: 2 ---- -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Error from '../../components/Error.astro'; -import Endpoint from '../../components/Endpoint.astro'; -import Badge from '../../components/Badge.astro'; - -A Loyalty Program Membership represents an Account's membership to a Loyalty Program. - -## Loyalty Program Membership Model - - - - The unique identifier of the Loyalty Program Membership. - - - - The [Account](/api/accounts/) that is being onboarded to the Loyalty Program. - - - - The id of the Loyalty Program that the Membership is created for. - - - - The display name of the Loyalty Program. - - - - The displayable description for the Loyalty Program. - - - - The status of the Loyalty Program Membership. - - - - The id of the [Media Upload](/api/media-uploads/) image of the Loyalty Program. - - - - The img URL of the Loyalty Program. - - - - When the Loyalty Program Membership was created. - - - - The User or API Key that created the Loyalty Program Membership. - - - - `true` if the Loyalty Program Membership is for testing purposes only. - - - ---- - - - ## Create Loyalty Program Memberships - - This endpoint allows you to create [ Loyalty Program Memberships ](#loyalty-program-membership-model) to onboard users to [ Loyalty Programs ](#loyalty-program-model). - - - - The [Account](/api/accounts/) that is being onboarded to the Loyalty Program. - - - - - - A membership has already been created for this account and this loyalty program. - - - - The account cannot be test if the loyalty program is not test. - - - diff --git a/src/content/api/loyalty-programs.mdoc b/src/content/api/loyalty-programs.mdoc new file mode 100644 index 000000000..daa38fe59 --- /dev/null +++ b/src/content/api/loyalty-programs.mdoc @@ -0,0 +1,94 @@ +--- +title: Loyalty Programs +description: Loyalty Program model and related endpoints +nav: + path: Loyalty Programs + order: 1 +--- +A loyalty program is a container for one or more [Promotions](/api/promotions), which is a mechanism to reward accounts for completing certain actions. + +## Loyalty Program Model + +{% properties %} + {% property name="id" type="string" %} + The unique identifier of the Loyalty Program. + {% /property %} + + {% property name="name" type="string" %} + The display name of the Loyalty Program. + {% /property %} + + {% property name="description" type="string" %} + The displayable description for the Loyalty Program. + {% /property %} + + {% property name="mediaUploadId" type="string" %} + The id of the [Media Upload](/api/media-uploads/) image of the Loyalty Program. + {% /property %} + + {% property name="img" type="string" %} + The img URL of the Loyalty Program. + {% /property %} + + {% property name="accountId" type="string" %} + The [Account](/api/accounts/) that will own the Loyalty Program. + {% /property %} + + {% property name="createdAt" type="timestamp" %} + When the Loyalty Program was created. + {% /property %} + + {% property name="createdBy" type="crn" %} + The User or API Key that created the Loyalty Program. + {% /property %} + + {% property name="test" type="boolean" %} + `true` if the Loyalty Program is for testing purposes only. + {% /property %} +{% /properties %} + +--- + +{% endpoint + path="/api/loyalty-programs" + filename="loyalty-programs-create" +%} + ## Create Loyalty Program {% badge type="experimental" /%} + + This endpoint allows you to create a [Loyalty Program](#loyalty-program-model). + + {% properties %} + {% property name="name" type="string" required=true %} + The display name of the Loyalty Program. + {% /property %} + + {% property name="accountId" type="string" required=true %} + The [Account](/api/accounts/) that will own the Loyalty Program. + {% /property %} + + {% property name="description" type="string" %} + The displayable description for the Loyalty Program. + {% /property %} + + {% property name="mediaUploadId" type="string" %} + The id of the [Media Upload](/api/media-uploads/) image of the Loyalty Program. + {% /property %} + {% /properties %} + + {% properties heading="Errors" %} + {% error code="403" message="INVALID_ACCOUNT_TYPE" %} + The Account must be type `org`. + {% /error %} + {% /properties %} +{% /endpoint %} + +--- + +{% endpoint + path="/api/accounts/{accountId}/loyalty-programs" + filename="loyalty-programs-list-by-accountId" +%} + ## List Loyalty Programs by Account Id {% badge type="experimental" /%} + + Returns a [paginated](/api/pagination/) list of [Loyalty Programs](#loyalty-program-model) for an Account. +{% /endpoint %} diff --git a/src/content/api/loyalty-programs.mdx b/src/content/api/loyalty-programs.mdx deleted file mode 100644 index aece45598..000000000 --- a/src/content/api/loyalty-programs.mdx +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: Loyalty Programs -description: Loyalty Program model and related endpoints -nav: - path: Loyalty Programs - order: 1 ---- -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Error from '../../components/Error.astro'; -import Endpoint from '../../components/Endpoint.astro'; -import Badge from '../../components/Badge.astro'; - -A loyalty program is a container for one or more [Promotions](/api/promotions), which is a mechanism to reward accounts for completing certain actions. - -## Loyalty Program Model - - - - The unique identifier of the Loyalty Program. - - - - The display name of the Loyalty Program. - - - - The displayable description for the Loyalty Program. - - - - The id of the [Media Upload](/api/media-uploads/) image of the Loyalty Program. - - - - The img URL of the Loyalty Program. - - - - The [Account](/api/accounts/) that will own the Loyalty Program. - - - - When the Loyalty Program was created. - - - - The User or API Key that created the Loyalty Program. - - - - `true` if the Loyalty Program is for testing purposes only. - - - ---- - - - ## Create Loyalty Program - - This endpoint allows you to create a [ Loyalty Program ](#loyalty-program-model). - - - - The display name of the Loyalty Program. - - - - The [Account](/api/accounts/) that will own the Loyalty Program. - - - - The displayable description for the Loyalty Program. - - - - The id of the [Media Upload](/api/media-uploads/) image of the Loyalty Program. - - - - - - The Account must be type `org`. - - - - ---- - - - ## List Loyalty Programs by Account Id - - Returns a [paginated](/api/pagination/) list of [Loyalty Programs](#loyalty-program-model) for an Account. - diff --git a/src/content/api/managed-integrations.mdoc b/src/content/api/managed-integrations.mdoc new file mode 100644 index 000000000..50f2e1570 --- /dev/null +++ b/src/content/api/managed-integrations.mdoc @@ -0,0 +1,325 @@ +--- +title: Managed Integrations +description: Managed Integration model and related endpoints +nav: + path: Integrations + order: 3 +--- +A Managed Integration is an [Integration](/api/integrations) which a third party can control. + +## Managed Integration Model + + +{% properties %} + {% property name="id" type="string" %} + The Managed Integration's unique identifier. + {% /property %} + + {% property name="type" type="string" %} + The type of Managed Integration. Supported types are `paypal-referral`. + {% /property %} + + {% property name="enabled" type="boolean" %} + Flag indicating whether the Managed Integration should become active or inactive. + {% /property %} + + {% property name="status" type="string" %} + Current status of the Managed Integration. Supported values are `created`, `pending`, `provisioning`, `active`, `inactive` and `archived`. + {% /property %} + + {% property name="externalId" type="string" %} + Field used to reference an id from an external system. + {% /property %} + + {% property name="params" type="object" %} + [Params](#params-model) depending on the Managed Integration type. + {% /property %} + + {% property name="createdAt" type="timestamp" %} + When the Managed Integration was created. + {% /property %} + + {% property name="createdBy" type="crn" %} + The User or API Key that created the Managed Integration. + {% /property %} + + {% property name="updatedAt" type="timestamp" %} + When the Managed Integration was updated. + {% /property %} + + {% property name="updatedBy" type="crn" %} + The User or API Key that updated the Managed Integration. + {% /property %} + + {% property name="claimedByAccountId" type="string" %} + Centrapay account id used to claim the Managed Integration. + {% /property %} + + {% property name="claimedBy" type="crn" %} + The User or API Key that claimed the Managed Integration. + {% /property %} + + {% property name="claimedAt" type="timestamp" %} + When the Managed Integration was claimed. + {% /property %} + + {% property name="invitation" type="object" %} + A summary of the associated [Invitation](/api/invitations). See [Invitation Summary](#invitation-summary-model). + {% /property %} + + {% property name="inProgress" type="boolean" %} + Flag indicating whether a status transition is in progress. + {% /property %} + + {% property name="test" type="boolean" %} + A flag which is present if the Managed Integration is for testing. + {% /property %} +{% /properties %} + +--- + +## Invitation Summary Model + +A summary of the [Invitation](/api/invitations) for a Managed Integration. + +{% properties %} + {% property name="id" type="string" %} + The Invitation's unique identifier. + {% /property %} + + {% property name="code" type="string" %} + The Invitation code. + {% /property %} + + {% property name="expiresAt" type="timestamp" %} + When the Invitation expires. + {% /property %} +{% /properties %} + +--- + +## Merchant Model + +{% properties %} + {% property name="partnerMerchantId" type="string" required=true %} + The unique id of the merchant in your system. + {% /property %} + + {% property name="merchantName" type="string" required=true %} + The name of the merchant. + {% /property %} + + {% property name="merchantStreetNumberName" type="string" required=true %} + The street number and name where the merchant is located. + {% /property %} + + {% property name="merchantSuburb" type="string" required=true %} + The suburb where the merchant is located. + {% /property %} + + {% property name="merchantTown" type="string" required=true %} + The town where the merchant is located. + {% /property %} + + {% property name="merchantCountry" type="string" required=true %} + The country where the merchant is located. + {% /property %} + + {% property name="merchantPostCode" type="string" required=true %} + The post code where the merchant is located. + {% /property %} + + {% property name="merchantCategoryCode" type="string" %} + The merchant category code. + {% /property %} + + {% property name="settlementAcct" type="string" required=true %} + The bank account number for settlement. + {% /property %} + + {% property name="chargeAcct" type="string" %} + The bank account number for charges. + {% /property %} + + {% property name="merchantContactName" type="string" required=true %} + The merchant contact name. + {% /property %} + + {% property name="merchantEmail" type="string" required=true %} + The merchant email address. + {% /property %} + + {% property name="merchantContactNumber" type="string" %} + The merchant contact number + {% /property %} + + {% property name="terminals" type="object" %} + Array of [Terminal](#terminal-model) information. + {% /property %} +{% /properties %} + +--- + +## Terminal Model + +{% properties %} + {% property name="provider" type="object" required=true %} + The terminal provider Request. Refer to [Integration Types](/api/integration-requests#integration-types). + {% /property %} + + {% property name="terminalId" type="string" required=true %} + The software or logical id of the payment terminal. + {% /property %} + + {% property name="kitId" type="string" required=true %} + The hardware id or serial number of the payment terminal. + {% /property %} + + {% property name="reseller" type="string" %} + The terminal reseller. + {% /property %} + + {% property name="kitType" type="string" %} + The model of the payment terminal. + {% /property %} +{% /properties %} + +--- + +## Params Model + +### paypal-referral + +{% properties %} + {% property name="centrapayMerchantId" type="string" %} + The ID of the Centrapay merchant that will be onboarded. + {% /property %} + + {% property name="email" type="string" %} + The email address to send the PayPal referral to. + {% /property %} +{% /properties %} + +### quartz-business + +{% properties %} + {% property name="partnerBusinessId" type="string" required=true %} + The unique id of the business in your system. + {% /property %} + + {% property name="nzbn" type="string" %} + The unique NZBN identifier. + {% /property %} + + {% property name="companyName" type="string" required=true %} + The name of the company. + {% /property %} + + {% property name="tradingName" type="string" %} + The trading name of the company. + {% /property %} + + {% property name="entityType" type="string" %} + The type of the entity. + {% /property %} + + {% property name="businessStreetNumberName" type="string" %} + The street number and name where the business is located. + {% /property %} + + {% property name="businessSuburb" type="string" %} + The suburb where the business is located. + {% /property %} + + {% property name="businessTown" type="string" %} + The town where the business is located. + {% /property %} + + {% property name="businessCountry" type="string" %} + The country where the business is located. + {% /property %} + + {% property name="businessPostCode" type="string" %} + The post code where the business is located. + {% /property %} + + {% property name="primaryContactName" type="string" required=true %} + The name of the primary contact of the business. + {% /property %} + + {% property name="primaryContactEmail" type="string" required=true %} + The email address of the primary contact of the business. + {% /property %} + + {% property name="merchants" type="object" %} + Array of [Merchant](#merchant-model) information. + {% /property %} +{% /properties %} + +--- + +{% endpoint + path="/api/managed-integrations/{type}/{externalId}" + filename="managed-integrations-create-or-update" +%} + ## Create or Update Managed Integration + + This endpoint allows you to create or update a Managed Integration. + + {% properties %} + {% property name="enabled" type="boolean" required=true %} + Flag indicating whether the Managed Integration should become active or inactive. + {% /property %} + + {% property name="params" type="object" required=true %} + [Params](#params-model) depending on the Managed Integration type. + {% /property %} + + {% property name="test" type="boolean" %} + Flag indicating the Managed Integration is for testing, this cannot be changed once the resource has been created. + {% /property %} + {% /properties %} + + {% properties heading="Errors" %} + {% error code="400" message="INVALID_PARAMS" %} + Invalid [Params](#params-model) provided for Managed Integration type. + {% /error %} + + {% error code="403" message="MERCHANT_LIVENESS_MISMATCH" %} + The `test` flag on the merchant doesn't match the `test` flag on the `paypal-referral` managed integration. + {% /error %} + + {% error code="403" message="MERCHANT_NOT_FOUND" %} + The merchant is not found with the `centrapayMerchantId` on the `paypal-referral` managed integration. + {% /error %} + {% /properties %} +{% /endpoint %} + +--- + +{% endpoint + path="/api/managed-integrations/{type}/{externalId}" + filename="managed-integrations-get" +%} + ## Get Managed Integration + + This endpoint allows you to retrieve a Managed Integration by type and external id. +{% /endpoint %} + +--- + +{% endpoint + path="/api/accounts/{accountId}/managed-integrations" + filename="managed-integrations-list-by-accountId" +%} + ## List Managed Integration + + This endpoint allows you to retrieve the list of managed integrations for an account. + Returns a [paginated](/api/pagination/) list of [Managed Integrations](#managed-integration-model) for an Account. + + {% properties %} + {% property name="pageKey" type="string" %} + Used to retrieve the next page of items. + {% /property %} + {% /properties %} +{% /endpoint %} diff --git a/src/content/api/managed-integrations.mdx b/src/content/api/managed-integrations.mdx deleted file mode 100644 index e2c2d87ee..000000000 --- a/src/content/api/managed-integrations.mdx +++ /dev/null @@ -1,330 +0,0 @@ ---- -title: Managed Integrations -description: Managed Integration model and related endpoints -nav: - path: Integrations - order: 3 ---- -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Error from '../../components/Error.astro'; -import Endpoint from '../../components/Endpoint.astro'; - -A Managed Integration is an [Integration](/api/integrations) which a third party can control. - -## Managed Integration Model - - - - - The Managed Integration's unique identifier. - - - - The type of Managed Integration. Supported types are `paypal-referral`. - - - - Flag indicating whether the Managed Integration should become active or inactive. - - - - Current status of the Managed Integration. Supported values are `created`, `pending`, `provisioning`, `active`, `inactive` and `archived`. - - - - Field used to reference an id from an external system. - - - - [Params](#params-model) depending on the Managed Integration type. - - - - When the Managed Integration was created. - - - - The User or API Key that created the Managed Integration. - - - - When the Managed Integration was updated. - - - - The User or API Key that updated the Managed Integration. - - - - Centrapay account id used to claim the Managed Integration. - - - - The User or API Key that claimed the Managed Integration. - - - - When the Managed Integration was claimed. - - - - A summary of the associated [Invitation](/api/invitations). See [Invitation Summary](#invitation-summary-model). - - - - Flag indicating whether a status transition is in progress. - - - - A flag which is present if the Managed Integration is for testing. - - - ---- - -## Invitation Summary Model - -A summary of the [Invitation](/api/invitations) for a Managed Integration. - - - - The Invitation's unique identifier. - - - - The Invitation code. - - - - When the Invitation expires. - - - ---- - -## Merchant Model - - - - The unique id of the merchant in your system. - - - - The name of the merchant. - - - - The street number and name where the merchant is located. - - - - The suburb where the merchant is located. - - - - The town where the merchant is located. - - - - The country where the merchant is located. - - - - The post code where the merchant is located. - - - - The merchant category code. - - - - The bank account number for settlement. - - - - The bank account number for charges. - - - - The merchant contact name. - - - - The merchant email address. - - - - The merchant contact number - - - - Array of [Terminal](#terminal-model) information. - - - ---- - -## Terminal Model - - - - The terminal provider Request. Refer to [Integration Types](/api/integration-requests#integration-types). - - - - The software or logical id of the payment terminal. - - - - The hardware id or serial number of the payment terminal. - - - - The terminal reseller. - - - - The model of the payment terminal. - - - ---- - -## Params Model - -### paypal-referral - - - - The ID of the Centrapay merchant that will be onboarded. - - - - The email address to send the PayPal referral to. - - - -### quartz-business - - - - The unique id of the business in your system. - - - - The unique NZBN identifier. - - - - The name of the company. - - - - The trading name of the company. - - - - The type of the entity. - - - - The street number and name where the business is located. - - - - The suburb where the business is located. - - - - The town where the business is located. - - - - The country where the business is located. - - - - The post code where the business is located. - - - - The name of the primary contact of the business. - - - - The email address of the primary contact of the business. - - - - Array of [Merchant](#merchant-model) information. - - - ---- - - - ## Create or Update Managed Integration - - This endpoint allows you to create or update a Managed Integration. - - - - Flag indicating whether the Managed Integration should become active or inactive. - - - - [Params](#params-model) depending on the Managed Integration type. - - - - Flag indicating the Managed Integration is for testing, this cannot be changed once the resource has been created. - - - - - - Invalid [Params](#params-model) provided for Managed Integration type. - - - - The `test` flag on the merchant doesn't match the `test` flag on the `paypal-referral` managed integration. - - - - The merchant is not found with the `centrapayMerchantId` on the `paypal-referral` managed integration. - - - - ---- - - - ## Get Managed Integration - - This endpoint allows you to retrieve a Managed Integration by type and external id. - - ---- - - - ## List Managed Integration - - This endpoint allows you to retrieve the list of managed integrations for an account. - Returns a [paginated](/api/pagination/) list of [Managed Integrations](#managed-integration-model) for an Account. - - - - Used to retrieve the next page of items. - - - diff --git a/src/content/api/media-uploads.mdoc b/src/content/api/media-uploads.mdoc new file mode 100644 index 000000000..2f4ebe5da --- /dev/null +++ b/src/content/api/media-uploads.mdoc @@ -0,0 +1,83 @@ +--- +title: Media Uploads +description: Media Uploads API Reference +nav: + path: API + order: 15 +--- +## Media Upload Model + + +{% properties %} + {% property name="id" type="string" %} + The Media Upload's unique identifier. + {% /property %} + + {% property name="accountId" type="string" %} + The Media Upload's owning Centrapay Account id. + {% /property %} + + {% property name="mimeType" type="string" %} + The media (MIME) type of the upload. + {% /property %} + + {% property name="fileName" type="string" %} + The file name of the upload. + {% /property %} + + {% property name="createdAt" type="timestamp" %} + When the Media Upload was created. + {% /property %} + + {% property name="createdBy" type="crn" %} + The User or API Key that created the Media Upload. + {% /property %} + + {% property name="updatedAt" type="timestamp" %} + When the Media Upload was updated. + {% /property %} + + {% property name="updatedBy" type="crn" %} + The User or API Key that updated the Media Upload. + {% /property %} + + {% property name="uploadUrl" type="string" %} + A presigned URL that gives users time-limited permission to upload media. + {% /property %} +{% /properties %} + +--- + +{% endpoint + path="/api/media-uploads" + filename="media-uploads-create" +%} + ## Create a presigned URL for Media Upload {% badge type="experimental" /%} + + This endpoint allows you to upload a media file to Centrapay. It returns a presigned URL that can be used to download the media file. + + {% properties %} + {% property name="accountId" type="string" required=true %} + The Media Upload's owning Centrapay Account id. + {% /property %} + + {% property name="mimeType" type="string" required=true %} + The media (MIME) type of the upload. + {% /property %} + + {% property name="fileName" type="string" required=true %} + The file name of the upload. + {% /property %} + {% /properties %} +{% /endpoint %} + +--- + +{% endpoint + path="/api/media-uploads/{mediaUploadId}/location" + filename="media-uploads-get-location" +%} + ## Get Media Upload Location {% badge type="experimental" /%} + + This endpoint allows you to retrieve the upload location of a media file. +{% /endpoint %} diff --git a/src/content/api/media-uploads.mdx b/src/content/api/media-uploads.mdx deleted file mode 100644 index 605d38b8e..000000000 --- a/src/content/api/media-uploads.mdx +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Media Uploads -description: Media Uploads API Reference -nav: - path: API - order: 15 ---- -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Endpoint from '../../components/Endpoint.astro'; -import Badge from '../../components/Badge.astro'; - -## Media Upload Model - - - - - The Media Upload's unique identifier. - - - - The Media Upload's owning Centrapay Account id. - - - - The media (MIME) type of the upload. - - - - The file name of the upload. - - - - When the Media Upload was created. - - - - The User or API Key that created the Media Upload. - - - - When the Media Upload was updated. - - - - The User or API Key that updated the Media Upload. - - - - A presigned URL that gives users time-limited permission to upload media. - - - ---- - - - ## Create a presigned URL for Media Upload - - This endpoint allows you to upload a media file to Centrapay. It returns a presigned URL that can be used to download the media file. - - - - The Media Upload's owning Centrapay Account id. - - - - The media (MIME) type of the upload. - - - - The file name of the upload. - - - - ---- - - - ## Get Media Upload Location - - This endpoint allows you to retrieve the upload location of a media file. - diff --git a/src/content/api/merchant-configs.mdx b/src/content/api/merchant-configs.mdoc similarity index 60% rename from src/content/api/merchant-configs.mdx rename to src/content/api/merchant-configs.mdoc index bc2d38f4d..1ee346621 100644 --- a/src/content/api/merchant-configs.mdx +++ b/src/content/api/merchant-configs.mdoc @@ -5,75 +5,70 @@ nav: path: Merchants order: 2 --- -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Error from '../../components/Error.astro'; -import Endpoint from '../../components/Endpoint.astro'; - A Merchant Config defines the available payment options for paying a [Payment Request](/api/payment-requests). ## Merchant Config Model - - +{% properties %} + {% property name="paymentOptions" type="array" %} Array of [Payment Option Configs](#payment-option-config-model). - + {% /property %} - + {% property name="createdAt" type="timestamp" %} When the Merchant Config was created. - + {% /property %} - + {% property name="createdBy" type="crn" %} The User or API Key that created the Merchant Config. - + {% /property %} - + {% property name="updatedAt" type="timestamp" %} When the Merchant Config was updated. - + {% /property %} - + {% property name="updatedBy" type="crn" %} The User or API Key that updated the Merchant Config. - + {% /property %} - + {% property name="allowedRedirectUrls" type="array" experimental=true %} Allowed prefixes for the `redirectUrl` property on Payment Requests created with this Config. - - + {% /property %} +{% /properties %} --- ## Payment Option Config Model - - +{% properties %} + {% property name="type" type="string" required=true %} Type of payment method. See supported payment types below. - + {% /property %} - + {% property name="walletId" type="string" %} Merchant's Centrapay Settlement Wallet to receive payments. Optional for `centrapay.nzd` types, if not supplied then a settlement wallet may be created and then assigned. - + {% /property %} - + {% property name="paypalMerchantAccountId" type="string" %} Id of the PayPal merchants account. Required for `paypal.usd` and `venmo.usd` types. - + {% /property %} - + {% property name="paypalStoreId" type="string" %} Id of the PayPal merchants store. Required for `paypal.usd` and `venmo.usd` types. - + {% /property %} - + {% property name="farmlandsMerchantNumber" type="string" %} Id of the Farmlands merchant that funds will be transferred to. - + {% /property %} - + {% property name="externalMerchantId" type="string" %} Id of the external merchant. Required for `epay`, `stadius`, `quartz`, `payap-debit` and `uplinkapi.test` types. - + {% /property %} - + {% property name="collectionIds" type="string" %} Id of the [Token Collection](/api/tokens#token-collection-model), can be `discount` collection type. Required for `centrapay.ledger` types. - - + {% /property %} +{% /properties %} See [Asset Types](/api/asset-types) for values that may be present in the `type` field. @@ -81,86 +76,86 @@ See [Asset Types](/api/asset-types) for values that may be present in the `type` --- - +%} ## Create Merchant Config This endpoint allows you to create a Merchant Config for a Merchant. - - + {% properties %} + {% property name="paymentOptions" type="array" required=true %} A list of [Payment Option Configs](#payment-option-config-model). - - + {% /property %} + {% property name="allowedRedirectUrls" type="array" experimental=true %} Allowed prefixes for the `redirectUrl` property on Payment Requests created with this Config. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="INVALID_WALLET_TYPE" %} `walletId` does not belong to a [Settlement Wallet](/api/wallets#settlement-wallets). - - + {% /error %} + {% error code="403" message="LIVENESS_MISMATCH" %} Only [Merchants](/api/merchants) with the `test` flag can have merchant configs with test assets, vice versa - - + {% /error %} + {% error code="403" message="COLLECTIONS_INVALID" %} An item in the `collectionIds` array does not exist or does not belong to a supported collection type. - - - + {% /error %} + {% /properties %} +{% /endpoint %} --- - +%} ## Get Merchant Config This endpoint allows you to retrieve a Merchant Config by id. - +{% /endpoint %} --- - +%} ## List Merchant Configs This endpoint allows you to retrieve a list of Merchant Configs. - +{% /endpoint %} --- - +%} ## Update Merchant Config This endpoint allows you to update a Merchant Config. - - + {% properties %} + {% property name="paymentOptions" type="array" required=true %} A list of [Payment Option Configs](#payment-option-config-model). - - + {% /property %} + {% property name="allowedRedirectUrls" type="array" experimental=true %} Allowed prefixes for the `redirectUrl` property on Payment Requests created with this Config. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="INVALID_WALLET_TYPE" %} `walletId` does not belong to a [Settlement Wallet](/api/wallets#settlement-wallets). - - + {% /error %} + {% error code="403" message="LIVENESS_MISMATCH" %} Only [Merchants](/api/merchants) with the `test` flag can have merchant configs with test assets, vice versa - - + {% /error %} + {% error code="403" message="COLLECTIONS_INVALID" %} An item in the `collectionIds` array does not exist or does not belong to a supported collection type. - - - + {% /error %} + {% /properties %} +{% /endpoint %} diff --git a/src/content/api/merchants.mdx b/src/content/api/merchants.mdoc similarity index 68% rename from src/content/api/merchants.mdx rename to src/content/api/merchants.mdoc index b71f5c186..ecf3f6f5f 100644 --- a/src/content/api/merchants.mdx +++ b/src/content/api/merchants.mdoc @@ -5,79 +5,73 @@ nav: path: Merchants order: 1 --- -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Error from '../../components/Error.astro'; -import Badge from '../../components/Badge.astro'; -import Endpoint from '../../components/Endpoint.astro'; - A merchant is an initiator of [Payment Requests](/api/payment-requests). A Merchant has [Merchant Configs](/api/merchant-configs) which define the payment methods available for a Payment Request. ## Merchant Model - - +{% properties %} + {% property name="id" type="string" %} Merchant's unique identifier. - + {% /property %} - + {% property name="accountId" type="string" %} Id of Merchant's owning Centrapay account. - + {% /property %} - + {% property name="name" type="string" %} Merchant name. - + {% /property %} - + {% property name="country" type="string" %} Merchant [ISO 3166](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code. Must match the "region" on the [Account](/api/accounts). - + {% /property %} - + {% property name="createdAt" type="timestamp" %} When the Merchant was created. - + {% /property %} - + {% property name="createdBy" type="crn" %} The User or API Key that created the Merchant. - + {% /property %} - + {% property name="updatedAt" type="timestamp" %} When the Merchant was updated. - + {% /property %} - + {% property name="updatedBy" type="crn" %} The User or API Key that updated the Merchant. - + {% /property %} - + {% property name="test" type="boolean" %} Flag indicating merchant is for testing. - + {% /property %} - + {% property name="settlementConfig" type="object" %} Merchant [Settlement Config](#settlement-config-model). - + {% /property %} - + {% property name="type" type="string" %} Valid values: `physical` or `e-commerce`. Merchants with a physical store should provide type `physical`. Online only merchants should provide type `e-commerce`. E-commerce merchants will not be displayed in the store finder. - + {% /property %} - + {% property name="location" type="location" %} Physical Location of Merchant. It is highly recommended that you provide this otherwise, users won't be able to find you with our [Merchant Search](#search-merchants) API if they perform a origin + distance query. This field is forbidden when the provided type is `e-commerce`. - + {% /property %} - + {% property name="onboardingStatus" type="string" %} The onboarding status of the Merchant. See [Onboarding Statuses](#onboarding-statuses) for possible values. - + {% /property %} - + {% property name="onboardingStatusReason" type="string" %} The reason associated with the [Onboarding Status](#onboarding-statuses). See [Onboarding Status Reasons](#onboarding-status-reasons) for possible values. - + {% /property %} - + {% property name="categoryCode" type="string" %} The category code assigned to the Merchant by Centrapay. Must be 4 digits. - - + {% /property %} +{% /properties %} ### Onboarding Statuses @@ -106,238 +100,238 @@ which define the payment methods available for a Payment Request. ## Settlement Config Model - - +{% properties %} + {% property name="bankAccountId" type="string" %} The id of the bank account funds should be settled into. This must belong to the account - - + {% /property %} +{% /properties %} --- ## Merchant Search Result Model - - +{% properties %} + {% property name="id" type="string" %} Merchant's unique identifier - + {% /property %} - + {% property name="name" type="string" %} Merchant's name - + {% /property %} - + {% property name="acceptedAssets" type="array" %} List of assets accepted by the merchant. See [Accepted Asset Model](#accepted-asset-model). - + {% /property %} - + {% property name="location" type="location" %} Physical location of the merchant - - + {% /property %} +{% /properties %} --- ## Accepted Asset Model - - +{% properties %} + {% property name="assetType" type="string" %} The [type](/api/asset-types) of the asset - + {% /property %} - + {% property name="products" type="object" %} List of [Products](#product-model) supported by the asset type. Only available for [centrapay.token](/api/assets#token-model) asset type. - - + {% /property %} +{% /properties %} --- ## Product Model - - +{% properties %} + {% property name="id" type="string" %} Product's unique identifier. - - + {% /property %} +{% /properties %} --- - +%} ## Create Merchant This endpoint allows you to create a Merchant. - - + {% properties %} + {% property name="accountId" type="string" required=true %} Id of Merchant's owning Centrapay account. - + {% /property %} - + {% property name="name" type="string" required=true %} Merchant name. - + {% /property %} - + {% property name="country" type="string" required=true %} Merchant [ISO 3166](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code. Must match the "region" on the [Account](/api/accounts). - + {% /property %} - + {% property name="test" type="boolean" required=true %} Flag indicating merchant is for testing. - + {% /property %} - + {% property name="settlementConfig" type="object" %} Merchant [Settlement Config](#settlement-config-model). - + {% /property %} - + {% property name="type" type="string" %} Valid values: `physical` or `e-commerce`. - + {% /property %} - + {% property name="location" type="location" %} Physical Location of Merchant. It is highly recommended that you provide this otherwise, users won't be able to find you with our [Merchant Search](#search-merchants) API if they perform a origin + distance query. - + {% /property %} - + {% property name="categoryCode" type="string" %} The category code assigned to the Merchant by Centrapay. Must be 4 digits. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="BANK_ACCOUNT_MISMATCH" %} The bank account in the settlement config does not belong to the same account. - + {% /error %} - + {% error code="403" message="ACCOUNT_REGION_MISMATCH" %} The merchant's "country" does not match the "region" on the Account. - - - + {% /error %} + {% /properties %} +{% /endpoint %} --- - +%} ## Get Merchant This endpoint allows you to retrieve a Merchant by id. - +{% /endpoint %} --- - +%} ## List Merchants for Account This endpoint allows you to retrieve a [paginated](/api/pagination) list of Merchants attached to an Account. - +{% /endpoint %} --- - +%} ## Update Merchant This endpoint allows you to update a Merchant. - - + {% properties %} + {% property name="name" type="string" %} Merchant name. - + {% /property %} - + {% property name="settlementConfig" type="object" %} Merchant [Settlement Config](#settlement-config-model). - + {% /property %} - + {% property name="location" type="location" %} Physical Location of Merchant. It is highly recommended that you provide this otherwise, users won't be able to find you with our [Merchant Search](#search-merchants) API if they perform a origin + distance query. - + {% /property %} - + {% property name="categoryCode" type="string" %} The category code assigned to the Merchant by Centrapay. Must be 4 digits. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="BANK_ACCOUNT_MISMATCH" %} The bank account in the settlement config does not belong to the same account. - - - + {% /error %} + {% /properties %} +{% /endpoint %} --- - +%} ## Set Merchant Onboarding Status This endpoint allows you to set the onboarding status of a Merchant. - - + {% properties %} + {% property name="onboardingStatus" type="string" required=true %} The onboarding status of the Merchant. See [Onboarding Statuses](#onboarding-statuses) for possible values. - + {% /property %} - + {% property name="onboardingStatusReason" type="string" %} The reason associated with the [Onboarding Status](#onboarding-statuses). Required if the onboardingStatus is `on-hold` or `deactivated`. See [Onboarding Status Reasons](#onboarding-status-reasons) for possible values. - - - + {% /property %} + {% /properties %} +{% /endpoint %} --- - +%} ## Search Merchants Returns a [paginated](/api/pagination) response of [Merchant Search Results](#merchant-search-result-model) that match the search query. This endpoint does not require [Auth](/api/auth). ### Query Parameters - - + {% properties %} + {% property name="origin" type="string" %} The point to be searched around, formatted as a latitude,longitude - + {% /property %} - + {% property name="distance" type="number" %} The distance from the origin to be searched around in km - + {% /property %} - + {% property name="asset" type="string" %} A string of the format `assetType`, `productId` describing the asset where `assetType` is the type of [asset](/api/asset-types) to filter the merchants by and `productId` is the asset's collectionId for [centrapay.token](/api/assets#token-model) asset types. - + {% /property %} - + {% property name="name" type="string" %} Name of the merchant - + {% /property %} - + {% property name="pageKey" type="string" %} pageKey of next merchant to fetch - + {% /property %} - + {% property name="paginationLimit" type="string" %} Maximum amount of merchants to return - - - + {% /property %} + {% /properties %} +{% /endpoint %} --- - - ## List Merchants +%} + ## List Merchants {% badge type="deprecated" /%} Returns a [paginated](/api/pagination) list of Merchants which belong to the authenticated subject. - +{% /endpoint %} diff --git a/src/content/api/object-ids.mdx b/src/content/api/object-ids.mdoc similarity index 100% rename from src/content/api/object-ids.mdx rename to src/content/api/object-ids.mdoc diff --git a/src/content/api/pagination.mdx b/src/content/api/pagination.mdoc similarity index 65% rename from src/content/api/pagination.mdx rename to src/content/api/pagination.mdoc index 27a3da62b..a8870cab3 100644 --- a/src/content/api/pagination.mdx +++ b/src/content/api/pagination.mdoc @@ -5,11 +5,6 @@ nav: path: API order: 5 --- -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import CodePanel from '../../components/CodePanel.astro'; -import Endpoint from '../../components/Endpoint.astro'; - Pagination allows a listing endpoint to return a subset of results. The goal is to reduce memory usage and speed up page rendering. @@ -23,25 +18,25 @@ bring support to GET endpoints for listing, these conventions will be followed. ## Pagination Model - - +{% properties %} + {% property name="items" type="array" %} A list of items from the current page. - - + {% /property %} + {% property name="nextPageKey" type="string" %} Can be used to fetch the next page, not present on the last page. - - + {% /property %} +{% /properties %} --- - - - +%} + {% properties %} + {% property name="pageKey" type="string" %} Used to retrieve the next page of items. - - - + {% /property %} + {% /properties %} +{% /endpoint %} diff --git a/src/content/api/patron-codes.mdx b/src/content/api/patron-codes.mdoc similarity index 66% rename from src/content/api/patron-codes.mdx rename to src/content/api/patron-codes.mdoc index bb074df3b..62d47958a 100644 --- a/src/content/api/patron-codes.mdx +++ b/src/content/api/patron-codes.mdoc @@ -5,59 +5,50 @@ nav: path: Scanned Codes order: 2 --- -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Error from '../../components/Error.astro'; -import Endpoint from '../../components/Endpoint.astro'; -import CodePanel from '../../components/CodePanel.astro'; - A Patron Code is an alternative to presenting a QR code where that option isn’t available. ## Patron Code Model - - +{% properties %} + {% property name="id" type="string" %} The Patron Code's unique identifier. - + {% /property %} - + {% property name="barcode" type="string" %} ✩ Field to display in barcode format. - + {% /property %} - + {% property name="createdAt" type="timestamp" %} Date when the Patron Code was created. - + {% /property %} - + {% property name="expiresAt" type="timestamp" %} Date when the Patron Code will expire. - + {% /property %} - + {% property name="appName" type="string" deprecated=true %} The app used to create the Patron Code. - + {% /property %} - + {% property name="accountId" type="string" %} The account id of the creator of the patron code. - + {% /property %} - + {% property name="testScenarioName" type="string" %} The [Test Scenario Name](#test-scenario-name) of the Patron Code. - - + {% /property %} +{% /properties %} ✩ Barcode is a 16 digit number. The first 6 digits are a Centrapay defined prefix, then a 9 digit code, then a luhn checksum digit. - - - ```bash title="Barcode Breakdown" - 9 9 9 0 0 0 1 2 3 4 5 6 7 8 9 5 ❖ complete barcode - 9 9 9 0 0 0 - - - - - - - - - - ❖ centrapay prefix - - - - - - - 1 2 3 4 5 6 7 8 9 - ❖ code - - - - - - - - - - - - - - - - 5 ❖ luhn checksum - ``` - +```bash {% title="Barcode Breakdown" %} +9 9 9 0 0 0 1 2 3 4 5 6 7 8 9 5 ❖ complete barcode +9 9 9 0 0 0 - - - - - - - - - - ❖ centrapay prefix +- - - - - - 1 2 3 4 5 6 7 8 9 - ❖ code +- - - - - - - - - - - - - - - 5 ❖ luhn checksum +``` The Centrapay Prefix may present any of the following prefixes: @@ -92,44 +83,44 @@ be used with Payment Requests that will have a liveness of 'test'. The [Asset Ty --- - +%} ## Create Patron Code This endpoint allows you to create a Patron Code. You can find payment request information attached to a Patron Code by [polling for the Payment Request](/api/payment-requests#get-a-payment-request-linked-to-a-patron-code) using the transacting APIs. - +{% /endpoint %} --- - +%} ## Get Patron Code This endpoint allows you to retrieve a Patron Code by id. - +{% /endpoint %} --- - +%} ## Get Patron Code By Barcode This endpoint allows you to retrieve a Patron Code by barcode. - - + {% properties heading="Errors" %} + {% error code="400" message="CHECKSUM_FAILED" %} Luhn checksum digit doesn't pass. - + {% /error %} - + {% error code="403" message="PATRON_CODE_INVALID" %} Patron Code doesn't exist or it has expired. - - - + {% /error %} + {% /properties %} +{% /endpoint %} diff --git a/src/content/api/payment-requests.mdx b/src/content/api/payment-requests.mdoc similarity index 66% rename from src/content/api/payment-requests.mdx rename to src/content/api/payment-requests.mdoc index 46ad4d0e4..3f4ec4059 100644 --- a/src/content/api/payment-requests.mdx +++ b/src/content/api/payment-requests.mdoc @@ -5,11 +5,6 @@ nav: path: Payment Requests order: 1 --- -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Error from '../../components/Error.astro'; -import Endpoint from '../../components/Endpoint.astro'; - Payment Requests represent the intention for a merchant to receive payment for goods and services. Payment Requests define the amount to be paid and the Asset Types that are acceptable for payment. A Payment Request is shared with, and paid by, a patron. The [Payment Flows Guide](/guides/payment-flows/) has more details regarding negotiation of Payment Requests. @@ -31,151 +26,151 @@ Centrapay Payment Requests are serviced via two sets of endpoints; the “next ## Payment Request Model - - +{% properties %} + {% property name="id" type="string" %} The Payment Request id. - - + {% /property %} + {% property name="shortCode" type="string" %} A shorter id that can be used to identify the Payment Request for up to two years. - - + {% /property %} + {% property name="url" type="string" %} The URL for a Centrapay webpage that allows the user to pay the Payment Request. - - + {% /property %} + {% property name="value" type="monetary" %} The canonical value of the Payment Request. Must be less than 100000000 and positive. - - + {% /property %} + {% property name="paymentOptions" type="array" %} The [Payment Options](#payment-option-model), indicating valid asset for payment. - - + {% /property %} + {% property name="merchantId" type="string" %} The id of the [Merchant](/api/merchants) the Payment Request is on behalf of. - - + {% /property %} + {% property name="merchantName" type="string" %} The name of the Merchant the Payment Request is on behalf of. - - + {% /property %} + {% property name="configId" type="string" %} The [Merchant Config](/api/merchant-configs) id used to configure the payment options. - - + {% /property %} + {% property name="status" type="string" %} Valid values: `new`, `paid`, `cancelled`, or `expired`. - - + {% /property %} + {% property name="liveness" type="string" %} Indicates liveness of assets that are accepted, determined by the payment options. Values are `main` or `test`. - - + {% /property %} + {% property name="createdAt" type="timestamp" %} When the Payment Request was created. - - + {% /property %} + {% property name="updatedAt" type="timestamp" %} When the Payment Request was updated. - - + {% /property %} + {% property name="expiresAt" type="timestamp" %} When the Payment Request expires. - - + {% /property %} + {% property name="merchantConditions" type="array" %} A dynamic list of [Payment Conditions](#payment-condition-model) that require operator approval to complete a payment. Conditions are calculated when [polling a Payment Request](#get-a-payment-request). - - + {% /property %} + {% property name="remainingAmount" type="bignumber" %} The amount of the Payment Request which has not been paid for. - - + {% /property %} + {% property name="patronCodeId" type="string" %} The id of a [Patron Code](/api/patron-codes) the Payment Request is attached to. - - + {% /property %} + {% property name="barcode" type="string" %} [Scanned Code](/api/scanned-codes) used to create the Payment Request. Required when the [Quick Pay](/guides/payment-flows/#quick-pay) payment flow is used. - - + {% /property %} + {% property name="barcodeType" type="string" %} Indicates the provider of a barcode, e.g. `ticketek`. - - + {% /property %} + {% property name="collectionId" type="string" %} The identifier of the [Token Collection](/api/tokens). - - + {% /property %} + {% property name="expirySeconds" type="number" %} The expiry seconds used to configure the Payment Request expiry. - - + {% /property %} + {% property name="lineItems" type="array" experimental=true %} The [Line Items](#line-item-model) being paid for. - - + {% /property %} + {% property name="purchaseOrderRef" type="string" %} A reference to a purchase order for this Payment Request. - - + {% /property %} + {% property name="invoiceRef" type="string" %} A reference to an invoice for this Payment Request. Must be less than or equal to 128 characters. - - + {% /property %} + {% property name="redirectCancelUrl" type="string" experimental=true %} URL to redirect the user to after they pay the Payment Request. Must start with one of the allowedRedirectUrls for the [Merchant Config](/api/merchant-configs). - - + {% /property %} + {% property name="redirectPaidUrl" type="string" experimental=true %} URL to redirect the user to after they cancel the Payment Request. Must start with one of the allowedRedirectUrls for the [Merchant Config](/api/merchant-configs). - - + {% /property %} + {% property name="externalRef" type="string" %} An external reference to the Payment Request. - - + {% /property %} + {% property name="terminalId" type="string" %} The software or logical id of the payment terminal. - - + {% /property %} + {% property name="deviceId" type="string" %} The hardware id or serial number of the payment terminal. - - + {% /property %} + {% property name="operatorId" type="string" %} POS operator Id. - - + {% /property %} + {% property name="createdByAccountId" type="string" %} Id of the [Centrapay Account](/api/accounts) creating the Payment Request. - - + {% /property %} + {% property name="createdByAccountName" type="string" %} Name of the [Centrapay Account](/api/accounts) creating the Payment Request. - - + {% /property %} + {% property name="conditionsEnabled" type="boolean" %} Flag to indicate that a merchant is able to accept [Payment Conditions](#payment-condition-model). - - + {% /property %} + {% property name="patronNotPresent" type="boolean" %} Flag to indicate the patron is not physically present. This may affect payment conditions or available [Payment Options](#payment-option-model). - - + {% /property %} + {% property name="cancellationReason" type="string" %} The reason that the Payment Request was cancelled. See [Cancellation Reasons](#cancellation-reasons) for possible values. - - + {% /property %} + {% property name="preAuth" type="boolean" %} Flag to indicate the if the request is a Pre Auth for supported [Asset Types](/api/asset-types). - - + {% /property %} + {% property name="preAuthExpiresAt" type="timestamp" %} Pre Auth completions and releases will be accepted until this time. - - + {% /property %} + {% property name="preAuthStatus" type="string" %} Describes which state a Pre Auth Payment Request is in. Valid values are `authorized` or `released`. - - + {% /property %} + {% property name="taxNumber" type="object" %} The value-added tax configuration for the [Business](/api/businesses) that the [Merchant](/api/merchants) belongs to. See [Tax Number](/api/businesses#tax-number-model). - - + {% /property %} + {% property name="partialAllowed" type="boolean" %} Flag to indicate that the Payment Request can be paid for partially. - - + {% /property %} + {% property name="paidBy" type="object" %} Shows the [Paid By](#paid-by-model) when a Payment Request is paid for with multiple Assets. - - + {% /property %} + {% property name="basketAmount" type="bignumber" %} The total amount of the transaction including non Centrapay payment methods. - - + {% /property %} +{% /properties %} --- ## Payment Option Model - - +{% properties %} + {% property name="assetType" type="string" %} An [Asset Type](/api/asset-types) reference. - - + {% /property %} + {% property name="amount" type="bignumber" %} The value required to pay using the canonical units for the Asset Type. - - + {% /property %} + {% property name="bitcoinAddress" type="string" %} ⭐️ Address to send Bitcoin, when the `assetType` is `bitcoin.*`. - - + {% /property %} + {% property name="acceptedCollections" type="array" %} [Accepted Collections](#accepted-collections) for the Payment Request, when the “assetType” is `centrapay.token.*`. - - + {% /property %} +{% /properties %} ⭐️ For Payment Options which specify an address, there’s a requirement to make a transaction on an external ledger. Once you have made that payment, you can use the transaction id to [Pay a Payment Request](#pay-a-payment-request) using the legacy payment API. @@ -187,14 +182,14 @@ If a Payment Request contains a `centrapay.token.*` Payment Option, an array of The Accepted Collections returned can be used to determine if a [Centrapay Token](/api/tokens) can be used to pay a Payment Request, and the Line Items able to be purchased using the Token. - - +{% properties %} + {% property name="id" type="string" %} The id of a collection that the Merchant accepts for the given Payment Request. - - + {% /property %} + {% property name="lineItems" type="array" %} The [Line Items](#line-item-model) that can be purchased by a [Centrapay Token](/api/tokens) with matching collection id. - - + {% /property %} +{% /properties %} --- @@ -211,20 +206,20 @@ Conditions can either be [accepted](#accept-a-payment-condition) or [declined](# the Payment Request will be cancelled. - - +{% properties %} + {% property name="id" type="bignumber" %} An enumerated identifier for the Payment Condition. - - + {% /property %} + {% property name="name" type="string" %} The name of the condition. - - + {% /property %} + {% property name="message" type="string" %} The human-readable description of the condition. - - + {% /property %} + {% property name="status" type="string" %} The status of the condition. Valid values include `accepted`, `declined`, `awaiting-merchant` or `void`. - - + {% /property %} +{% /properties %} --- @@ -237,60 +232,60 @@ Line items can include a discount amount. A discount that applies to multiple Line Items may be represented as a separate Line Item with a negative amount. - - +{% properties %} + {% property name="name" type="string" required=true %} The product description. - - + {% /property %} + {% property name="sku" type="string" %} The product (stock keeping unit) code. Required for [Token](/api/tokens/) redemptions. - - + {% /property %} + {% property name="qty" type="bignumber" required=true %} The product quantity (eg. item count, weight, volume etc). - - + {% /property %} + {% property name="price" type="bignumber" required=true %} The total price in cents for the line item (eg. `price = product price * qty - discounts + tax`). - - + {% /property %} + {% property name="tax" type="bignumber" %} Tax rate (percentage). - - + {% /property %} + {% property name="discount" type="bignumber" %} Discount amount in cents (tax exclusive). - - + {% /property %} + {% property name="productId" type="string" %} Manufacturer’s product identifier (eg GTIN/EAN). - - + {% /property %} + {% property name="restricted" type="boolean" %} Disallow payment with a “restricted” [Asset Type](/api/asset-types). - - + {% /property %} + {% property name="classification" type="object" %} [Product Classification](#product-classification). - - + {% /property %} +{% /properties %} --- ## Product Classification - - +{% properties %} + {% property name="type" type="string" %} The classification type. Currently only `GS1` is supported. See [GS1 Global Product Classification](https://www.gs1.org/standards/gpc). When `GS1` is used as the product classification type then the product code should be the GPC product brick identifier. - - + {% /property %} + {% property name="code" type="string" %} The classification code. - - + {% /property %} + {% property name="name" type="string" %} The classification title. - - + {% /property %} + {% property name="props" type="object" %} The product classification properties. Classification properties allow optional additional product characterizing attrubutes to be supplied. In the case of GS1 product classifications this corresponds to the GPC brick attributes. - - + {% /property %} +{% /properties %} --- @@ -298,33 +293,33 @@ A discount that applies to multiple Line Items may be represented as a separate The Paid By provides a summary of the transactions after the Payment Request was paid. - - +{% properties %} + {% property name="assetTotals" type="array" %} The [Asset Totals](#asset-totals) for each transacted Asset Type. - - + {% /property %} +{% /properties %} ## Asset Totals The Asset Totals provides a sum of every transaction for each [Asset Type](/api/asset-types) - - +{% properties %} + {% property name="type" type="string" %} The Asset Type used for the payment. - - + {% /property %} + {% property name="description" type="string" %} A human readable description of the Asset Type used. - - + {% /property %} + {% property name="settlementDate" type="timestamp" %} The estimated date that the Merchant can expect settlement of funds. - - + {% /property %} + {% property name="total" type="monetary" %} The total monetary value of the Asset Type used to pay a Payment Request. - - + {% /property %} + {% property name="lineItems" type="array" experimental=true %} The [Line Items](#line-item-model) paid for by the Asset Type. - - + {% /property %} +{% /properties %} --- @@ -334,71 +329,71 @@ A Payment Activity records a transaction that has happened on a Payment Request. Payment Activities are created when a Payment Request has been `created`, `paid`, `refunded`, `cancelled`, or `expired`. - - +{% properties %} + {% property name="id" type="string" %} The unique identifier of the Payment Activity. - - + {% /property %} + {% property name="type" type="string" %} The [Payment Activity Type](#payment-activity-types). - - + {% /property %} + {% property name="value" type="monetary" %} The value of the Payment Activity. Must be less than 100000000 and positive. - - + {% /property %} + {% property name="paymentRequestId" type="string" %} The Payment Request’s id. - - + {% /property %} + {% property name="merchantId" type="string" %} The Payment Request’s [Merchant](/api/merchants) id. - - + {% /property %} + {% property name="merchantConfigId" type="string" %} The Payment Request’s [Merchant Config](/api/merchant-configs) id. - - + {% /property %} + {% property name="merchantAccountId" type="string" %} The Payment Request’s Merchant [Account](/api/accounts) id. - - + {% /property %} + {% property name="merchantName" type="string" %} The Payment Request’s Merchant name. - - + {% /property %} + {% property name="createdAt" type="timestamp" %} When the activity was created. - - + {% /property %} + {% property name="createdBy" type="crn" %} The identity that created the activity. - - + {% /property %} + {% property name="paymentRequestCreatedBy" type="crn" %} The identity that created the Payment Request. - - + {% /property %} + {% property name="activityNumber" type="bignumber" %} Unique sequential number for the activity. - - + {% /property %} + {% property name="shortCode" type="string" %} A shorter id that can be used for up to two years. - - + {% /property %} + {% property name="assetType" type="string" %} The Asset Type for the `payment` or `refund` activity. - - + {% /property %} + {% property name="external" type="boolean" %} `true` if the Payment Activity is recording a transaction that occurred outside the Centrapay system. - - + {% /property %} + {% property name="cancellationReason" type="string" %} The reason that the Payment Request was cancelled. See [Cancellation Reasons](#cancellation-reasons) for possible values. - - + {% /property %} + {% property name="conditionId" type="number" %} The id of a Condition if the activity was for a Condition being accepted or declined. - - + {% /property %} + {% property name="idempotencyKey" type="string" %} Required when confirming a Payment Request. This is an identifier from your system to enforce uniqueness. - - + {% /property %} + {% property name="confirmationIdempotencyKey" type="string" %} Required when refunding a Pre Auth Confirmation. Should be the same as the idempotencyKey used for Confirmation. - - + {% /property %} + {% property name="preAuth" type="boolean" %} `true` if the related Payment Request is a Pre Auth. - - + {% /property %} + {% property name="paidBy" type="object" %} Shows the [Paid By](#paid-by-model) when a Payment Request is paid. - - + {% /property %} +{% /properties %} ### Payment Activity Types @@ -437,138 +432,138 @@ Payment Activities are created when a Payment Request has been `created`, `paid` --- - +%} ## Create a Payment Request This endpoint allows you to create a Payment Request. - - + {% properties %} + {% property name="configId" type="string" required=true %} The [Merchant Config](/api/merchant-configs) id used to configure the payment options. - - + {% /property %} + {% property name="value" type="monetary" required=true %} The canonical value of the Payment Request. Must be less than 100000000 and positive. - - + {% /property %} + {% property name="barcode" type="string" %} [Scanned Code](/api/scanned-codes) used to create the Payment Request. - - + {% /property %} + {% property name="barcodeType" type="string" %} Indicates the provider of a barcode, e.g. `ticketek`. - - + {% /property %} + {% property name="collectionId" type="string" %} The identifier of the [Token Collection](/api/tokens). - - + {% /property %} + {% property name="expirySeconds" type="number" %} The expiry seconds used to configure the Payment Request expiry. - - + {% /property %} + {% property name="lineItems" type="array" experimental=true %} The [Line Items](#line-item-model) being paid for. - - + {% /property %} + {% property name="purchaseOrderRef" type="string" %} A reference to a purchase order for this Payment Request. - - + {% /property %} + {% property name="invoiceRef" type="string" %} A reference to an invoice for this Payment Request. Must be less than or equal to 128 characters. - - + {% /property %} + {% property name="redirectCancelUrl" type="string" experimental=true %} URL to redirect the user to after they pay the Payment Request. Must start with one of the allowedRedirectUrls for the [Merchant Config](/api/merchant-configs). - - + {% /property %} + {% property name="redirectPaidUrl" type="string" experimental=true %} URL to redirect the user to after they cancel the Payment Request. Must start with one of the allowedRedirectUrls for the [Merchant Config](/api/merchant-configs). - - + {% /property %} + {% property name="externalRef" type="string" %} An external reference to the Payment Request. - - + {% /property %} + {% property name="terminalId" type="string" %} The software or logical id of the payment terminal. - - + {% /property %} + {% property name="deviceId" type="string" %} The hardware id or serial number of the payment terminal. - - + {% /property %} + {% property name="operatorId" type="string" %} POS operator Id. - - + {% /property %} + {% property name="createdByAccountName" type="string" %} Name of the [Centrapay Account](/api/accounts) creating the Payment Request. - - + {% /property %} + {% property name="conditionsEnabled" type="boolean" %} Flag to indicate that a merchant is able to accept [Payment Conditions](#payment-condition-model). - - + {% /property %} + {% property name="patronNotPresent" type="boolean" %} Flag to indicate the patron is not physically present. This may affect payment conditions or available [Payment Options](#payment-option-model). - - + {% /property %} + {% property name="preAuth" type="boolean" %} Flag to indicate the if the request is a Pre Auth for supported [Asset Types](/api/asset-types). - - + {% /property %} + {% property name="partialAllowed" type="boolean" %} Flag to indicate that the Payment Request can be paid for partially. - - + {% /property %} + {% property name="basketAmount" type="bignumber" %} The total amount of the transaction including non Centrapay payment methods. Required when `partialAllowed` is `true`. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="400" message="LINE_ITEMS_SUM_CHECK_FAILED" %} The sum value of the line items did not equal the value of the Payment Request. - - + {% /error %} + {% error code="400" message="CHECKSUM_FAILED" %} Luhn checksum digit doesn't pass. - - + {% /error %} + {% error code="403" message="REDIRECT_URL_INVALID" %} One or more of the supplied redirect urls do not start with one of the `allowedRedirectUrls` on the [Merchant Config](/api/merchant-configs). - - + {% /error %} + {% error code="403" message="PATRON_CODE_INVALID" %} [Patron Code](/api/patron-codes) doesn't exist or has expired. - - + {% /error %} + {% error code="403" message="NO_AVAILABLE_PAYMENT_OPTIONS" %} No payment options match the requested payment parameters. - - + {% /error %} + {% error code="403" message="TOKEN_COLLECTION_NOT_FOUND" %} The token collection does not exist. - - + {% /error %} + {% /properties %} - +{% /endpoint %} --- - +%} ## Get a Payment Request This endpoint allows you to retrieve a Payment Request. - +{% /endpoint %} --- - +%} ## Get a Payment Request by Short Code This endpoint returns the latest Payment Request that matches the given short code. - - + {% properties heading="Errors" %} + {% error code="400" message="CHECKSUM_FAILED" %} Luhn checksum digit doesn't pass. - - + {% /error %} + {% /properties %} - +{% /endpoint %} --- - +%} ## Get a Payment Request linked to a Patron Code This endpoint returns the latest Payment Request with status `new` that has been attached to a [Patron Code](/api/patron-codes). @@ -577,47 +572,47 @@ Payment Activities are created when a Payment Request has been `created`, `paid` This endpoint should be polled just after a user's Patron Code has been scanned. This will allow them to find the Payment Request and proceed to pay. - +{% /endpoint %} --- - +%} ## List Payment Requests by External Reference This endpoint returns a list of [Payment Requests](#payment-request-model) that match the given external reference. Results are [paginated](/api/pagination/). - - + {% properties %} + {% property name="accountId" type="string" required=true %} The id of the [Account](/api/accounts/) used to create the Payment Request. - - + {% /property %} + {% property name="pageKey" type="string" %} Used to retrieve the next page of items. Note: The `pageKey` value, if provided, needs to be URL-encoded. - - - + {% /property %} + {% /properties %} +{% /endpoint %} --- - +%} ## Get Payment Request Summary This endpoint allows you to retrieve the summary of a Payment Request while the status is `new`. - +{% /endpoint %} --- - +%} ## Pay a Payment Request To pay a Payment Request you must supply the name of the [Asset Type](/api/asset-types) and one of `assetId`, `transactionId` or `authorization`. @@ -625,184 +620,184 @@ Payment Activities are created when a Payment Request has been `created`, `paid` - Use `transactionId` to verify an external transaction such as a Bitcoin payment. - Use `authorization` to authorize an external transaction. - - + {% properties %} + {% property name="assetType" type="string" required=true %} An [Asset Type](/api/asset-types) reference. - - + {% /property %} + {% property name="assetId" type="string" %} The id of the Asset being used to make payment. - - + {% /property %} + {% property name="transactionId" type="string" %} Used to verify an external transaction eg Bitcoin. - - + {% /property %} + {% property name="authorization" type="string" %} Used to authorize an external transaction. - - + {% /property %} + {% property name="mode" type="string" %} The mode of payment. Valid values are `partial-payment` and `multi-asset-payment`. - - + {% /property %} + {% property name="amount" type="string" %} The value required to pay using the canonical units for the Asset Type. - - + {% /property %} + {% property name="externalPaymentRef" type="string" %} An external reference to the payment. Required when `assetType` is `farmlands.nzd.*`. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="INVALID_ASSET_TYPE" %} Either the merchant is not configured with the provided asset type or the asset type does not exist. - - + {% /error %} + {% error code="403" message="REQUEST_EXPIRED" %} Action cannot be completed because the request has expired. - - + {% /error %} + {% error code="403" message="REQUEST_PAID" %} Action cannot be completed because the request has been paid. - - + {% /error %} + {% error code="403" message="REQUEST_CANCELLED" %} Action cannot be completed because the request has already been cancelled. - - + {% /error %} + {% error code="403" message="INACTIVE_ASSET" %} The asset is not spendable. It may have been disabled, expired, or already spent. - - + {% /error %} + {% error code="403" message="INVALID_MERCHANT_CONFIG" %} The merchant is not configured properly to satisfy the Payment Request. This could be due to incorrect information, or the merchant’s credentials might be blocked by an external service. - - + {% /error %} + {% error code="403" message="QUOTA_EXCEEDED" %} The payment pay request exceeds the allowed spend quota supplied. - - + {% /error %} + {% error code="403" message="INSUFFICIENT_ASSET_VALUE" %} The asset has insufficient funds to pay the Payment Request or the transaction amount received by Centrapay is less than the total of the payment. - - + {% /error %} + {% error code="403" message="ASSET_REDEMPTION_DENIED" %} The asset redemption has been unsuccessful due to an error with provided payment parameters, the Merchant, or the Asset. - - + {% /error %} + {% error code="403" message="PAYMENT_DECLINED" %} The payment parameters were valid but payment was declined because additional payment restrictions were violated. - - + {% /error %} + {% /properties %} - +{% /endpoint %} --- - +%} ## Refund a Payment Request This endpoint allows you to initiate a refund of a Payment Request. The refund will be completed asynchronously. - - + {% properties %} + {% property name="value" type="monetary" required=true %} The canonical value of the Payment Request. Must be less than 100000000 and positive. - - + {% /property %} + {% property name="externalRef" type="string" required=true %} An external reference to the refund. - - + {% /property %} + {% property name="invoiceRef" type="string" %} A reference to an invoice for the refund. Must be less than or equal to 128 characters. - - + {% /property %} + {% property name="confirmationIdempotencyKey" type="string" %} Required when refunding a Pre Auth Confirmation. Should be the same as the idempotencyKey used for Confirmation. - - + {% /property %} + {% property name="lineItems" type="array" experimental=true %} The [Line Items](#line-item-model) being refunded. - - + {% /property %} + {% property name="merchantConfigId" type="string" %} The [Merchant Config](/api/merchant-configs) id of the refunding merchant when refunding a `farmlands.nzd.*` payment. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="400" message="LINE_ITEMS_SUM_CHECK_FAILED" %} The sum value of the line items did not equal the value of the refund. - - + {% /error %} + {% error code="403" message="NOT_PAID" %} The Payment Request has not been paid. - - + {% /error %} + {% error code="403" message="ALREADY_REFUNDED" %} The Payment Request already been refunded. If you want to perfom additional refunds then an `externalRef` is required. - - + {% /error %} + {% error code="403" message="INVALID_AMOUNT" %} The refund requested is greater than the refundable amount. - - + {% /error %} + {% error code="403" message="REPEAT_REFERENCE" %} A refund has already been requested with the same external reference. Refunding the payment request twice with the same external reference is not allowed. If the amount of the refund is the same we assume it is a repeat request and return 200. - - + {% /error %} + {% error code="403" message="PARTIAL_REFUNDS_NOT_ALLOWED" %} The Asset does not support partial refunds. - - + {% /error %} + {% error code="403" message="INACTIVE_ASSET" %} The Asset is not refundable. It may have been disabled, expired, or already refunded. - - + {% /error %} + {% error code="403" message="REFUND_NOT_SUPPORTED" %} The Asset type does not support refunds. - - + {% /error %} + {% error code="403" message="REFUND_WINDOW_EXCEEDED" %} The time since the payment exceeds the window of time a payment request can be refunded in. - - + {% /error %} + {% error code="403" message="PRE_AUTH_PENDING" %} The Pre Auth Payment Request has yet to be authorized. - - + {% /error %} + {% error code="403" message="CONFIRMATION_NOT_FOUND" %} The confirmationIdempotencyKey does not match a Confirmation on the Payment Request. - - + {% /error %} + {% error code="403" message="REFUND_DECLINED" %} The refund parameters were valid but refund was declined because additional business rules were violated. - - + {% /error %} + {% /properties %} - +{% /endpoint %} --- - +%} ## Void a Payment Request Voiding a payment request will cancel the request and trigger any refunds if necessary. - - + {% properties heading="Errors" %} + {% error code="403" message="VOID_WINDOW_EXCEEDED" %} The void window is closed 24 hours after the Payment Request `createdAt`. After the void window has closed if the Payment Request is paid, use [Refund](#refund-a-payment-request) endpoint to reverse the payment. - - + {% /error %} + {% error code="403" message="ALREADY_REFUNDED" %} The Payment Request already been refunded. - - + {% /error %} + {% error code="403" message="REPEAT_REFERENCE" %} A refund has already been requested with the same external reference. Refunding the payment request twice with the same external reference is not allowed. If the amount of the refund is the same we assume it is a repeat request and return 200. - - + {% /error %} + {% error code="403" message="INACTIVE_ASSET" %} The Asset is not refundable. It may have been disabled, expired, or already refunded. - - + {% /error %} + {% error code="403" message="REFUND_NOT_SUPPORTED" %} The Asset type does not support refunds. - - + {% /error %} + {% error code="403" message="REQUEST_EXPIRED" %} The Payment Request has expired. - - + {% /error %} + {% error code="403" message="PRE_AUTH_ALREADY_CONFIRMED" %} The Pre Auth Payment Request already has confirmations. Use [Refund](#refund-a-payment-request) endpoint to reverse the transaction. - - + {% /error %} + {% /properties %} - +{% /endpoint %} --- - +%} ## Release Pre Auth funds This endpoint allows you to release funds held for a Pre Auth Payment Request. @@ -810,23 +805,23 @@ Payment Activities are created when a Payment Request has been `created`, `paid` When you call release on a Pre Auth Payment Request any remaining funds that were being held for the authorization are returned to the asset, and a release Payment Activity is returned. If the authorization never completed, the Payment Request will instead be cancelled, and a cancellation Payment Activity will be returned. - - + {% properties heading="Errors" %} + {% error code="403" message="INVALID_PAYMENT_REQUEST_TYPE" %} The Payment Request is not related to a Pre Auth. - - + {% /error %} + {% error code="403" message="PRE_AUTH_RELEASED" %} `preAuthExpiresAt` has passed. - - + {% /error %} + {% /properties %} - +{% /endpoint %} --- - +%} ## Confirm Pre Auth Payment Request This endpoint allows you to make a confirmation against a Pre Auth Payment Request. @@ -835,122 +830,122 @@ Payment Activities are created when a Payment Request has been `created`, `paid` If our endpoint does not respond, you must retry until you get back a 200 or 403. If we recive 2 requests with the same `idempotencyKey`, we won't process the second and return the first response. - - + {% properties %} + {% property name="idempotencyKey" type="string" required=true %} This is an identifier from your system to enforce uniqueness. - - + {% /property %} + {% property name="invoiceRef" type="string" required=true %} A reference to an invoice for this Payment Request. Must be less than or equal to 128 characters. - - + {% /property %} + {% property name="lineItems" type="array" required=true experimental=true %} The [Line Items](#line-item-model) being confirmed. - - + {% /property %} + {% property name="value" type="monetary" %} The canonical value of the confirmation. Must be less than 100000000 and positive. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="INVALID_PAYMENT_REQUEST_TYPE" %} The Payment Request is not related to a Pre Auth. - - + {% /error %} + {% error code="403" message="PRE_AUTH_RELEASED" %} The Payment Request has been released or Pre Auth has expired. Remaining funds have been returned to the Patron. - - + {% /error %} + {% error code="403" message="PRE_AUTH_PENDING" %} The Payment Request has not been authorized. - - + {% /error %} + {% error code="403" message="REQUEST_CANCELLED" %} The Payment Request has been cancelled. - - + {% /error %} + {% error code="403" message="INVALID_AMOUNT" %} The confirmation is greater then the remaining funds on the authroization. - - + {% /error %} + {% error code="403" message="IDEMPOTENT_OPERATION_FAILED" %} There has already been a confirmation against the Payment Request with the same idempotencyKey but different content. - - + {% /error %} + {% /properties %} - +{% /endpoint %} --- - +%} ## List Payment Activities for a Merchant This endpoint allows you to list [Payment Activities](#payment-activity-model) for a Merchant. Results are [paginated](/api/pagination/) and ordered by descending activity created date. - - + {% properties %} + {% property name="merchantId" type="string" required=true %} The id of the [Merchant](/api/merchants/) the Payment Request is on behalf of. - - + {% /property %} + {% property name="pageKey" type="string" required=true %} Used to retrieve the next page of items. Note: The `pageKey` value, if provided, needs to be URL-encoded. - - - + {% /property %} + {% /properties %} +{% /endpoint %} --- - +%} ## List Payment Activities for a Payment Request This endpoint allows you to list [Payment Activities](#payment-activity-model) for a Payment Request. Results are ordered by descending activity created date. - +{% /endpoint %} --- - +%} ## Accept a Payment Condition Accept a [Payment Condition](#payment-condition-model) listed in `merchantConditions` with status `awaiting-merchant`. Returns a [Payment Activity](#payment-activity-model). - - + {% properties heading="Errors" %} + {% error code="403" message="PATRON_NOT_AUTHORIZED" %} The Payment Condition is `awaiting-merchant`, therefore the patron is not authorized to accept the condition. - - + {% /error %} + {% error code="403" message="MERCHANT_NOT_AUTHORIZED" %} The Payment Condition is `awaiting-patron`, therefore the merchant is not authorized to accept the condition. - - + {% /error %} + {% error code="403" message="CONDITION_ALREADY_SET" %} The Payment Condition has already been accepted or declined. - - - + {% /error %} + {% /properties %} +{% /endpoint %} --- - +%} ## Decline a Payment Condition Decline a [Payment Condition](#payment-condition-model) listed in `merchantConditions` with status `awaiting-merchant`. Returns a [Payment Activity](#payment-activity-model). - - + {% properties heading="Errors" %} + {% error code="403" message="PATRON_NOT_AUTHORIZED" %} The Payment Condition is `awaiting-merchant`, therefore the patron is not authorized to decline the condition. - - + {% /error %} + {% error code="403" message="MERCHANT_NOT_AUTHORIZED" %} The Payment Condition is `awaiting-patron`, therefore the merchant is not authorized to decline the condition. - - + {% /error %} + {% error code="403" message="CONDITION_ALREADY_SET" %} The Payment Condition has already been accepted or declined. - - - + {% /error %} + {% /properties %} +{% /endpoint %} diff --git a/src/content/api/profiles.mdoc b/src/content/api/profiles.mdoc new file mode 100644 index 000000000..3f0b4c89e --- /dev/null +++ b/src/content/api/profiles.mdoc @@ -0,0 +1,93 @@ +--- +title: Profiles +description: Profile model and related endpoints +nav: + path: API + order: 18 +--- +A profile represents a Centrapay user's attributes. + + +## Profile Model + +{% properties %} + {% property name="userId" type="string" %} + The Centrapay user id. + {% /property %} + + {% property name="givenName" type="string" %} + First name. + {% /property %} + + {% property name="familyName" type="string" %} + Last name. + {% /property %} + + {% property name="featureUpdates" type="boolean" %} + Whether a user would like to receive emails for feature updates. + {% /property %} + + {% property name="marketingUpdates" type="boolean" %} + Whether a user would like to receive emails for marketing updates. + {% /property %} + + {% property name="email" type="string" %} + Email address. + {% /property %} + + {% property name="emailVerified" type="boolean" %} + Flag indicating the verification status of the email address. + {% /property %} + + {% property name="phoneNumber" type="string" %} + The user's phone number. + {% /property %} + + {% property name="phoneVerified" type="boolean" %} + Flag indicating the verification status of the phone number. + {% /property %} +{% /properties %} + +--- + +{% endpoint + path="/api/me/profile/update" + filename="profiles-update" +%} + ## Update Profile {% badge type="experimental" /%} + + Update a user’s mutable attributes. At least one field must be provided in the request. + + {% properties %} + {% property name="givenName" type="string" %} + First name. + {% /property %} + + {% property name="familyName" type="string" %} + Last name. + {% /property %} + + {% property name="featureUpdates" type="boolean" %} + Whether a user would like to receive emails for feature updates. + {% /property %} + + {% property name="marketingUpdates" type="boolean" %} + Whether a user would like to receive emails for marketing updates. + {% /property %} + + {% property name="email" type="string" %} + Email address. + {% /property %} + {% /properties %} +{% /endpoint %} + +--- + +{% endpoint + path="/api/users/{userId}/profile" + filename="profiles-get" +%} + ## Get Profile {% badge type="experimental" /%} + + This endpoint allows you to retrieve a user's Profile. +{% /endpoint %} diff --git a/src/content/api/profiles.mdx b/src/content/api/profiles.mdx deleted file mode 100644 index c73ab8775..000000000 --- a/src/content/api/profiles.mdx +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: Profiles -description: Profile model and related endpoints -nav: - path: API - order: 18 ---- -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Badge from '../../components/Badge.astro'; -import Endpoint from '../../components/Endpoint.astro'; - -A profile represents a Centrapay user's attributes. - - -## Profile Model - - - - The Centrapay user id. - - - - First name. - - - - Last name. - - - - Whether a user would like to receive emails for feature updates. - - - - Whether a user would like to receive emails for marketing updates. - - - - Email address. - - - - Flag indicating the verification status of the email address. - - - - The user's phone number. - - - - Flag indicating the verification status of the phone number. - - - ---- - - - ## Update Profile - - Update a user’s mutable attributes. At least one field must be provided in the request. - - - - First name. - - - - Last name. - - - - Whether a user would like to receive emails for feature updates. - - - - Whether a user would like to receive emails for marketing updates. - - - - Email address. - - - - ---- - - - ## Get Profile - - This endpoint allows you to retrieve a user's Profile. - diff --git a/src/content/api/promotion-memberships.mdx b/src/content/api/promotion-memberships.mdoc similarity index 60% rename from src/content/api/promotion-memberships.mdx rename to src/content/api/promotion-memberships.mdoc index 2af96a846..db7372a79 100644 --- a/src/content/api/promotion-memberships.mdx +++ b/src/content/api/promotion-memberships.mdoc @@ -5,113 +5,107 @@ nav: path: Loyalty Programs order: 4 --- -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Endpoint from '../../components/Endpoint.astro'; -import Badge from '../../components/Badge.astro'; -import Error from '../../components/Error.astro'; - Promotion Memberships represents an [Account's](/api/accounts) membership to a [Promotion](/api/promotions). Each Promotion Membership carries progress towards completing the Promotion. Promotion Memberships are created automatically for the account when a [Loyalty Program Membership](/api/loyalty-program-memberships) is created. ## Promotion Membership Model - - +{% properties %} + {% property name="id" type="string" %} The unique identifier for the Promotion. - + {% /property %} - + {% property name="accountId" type="string" %} The ID of the [Account](/api/accounts) that owns the Promotion. - + {% /property %} - + {% property name="name" type="string" %} The display name of the Promotion. - + {% /property %} - + {% property name="programId" type="string" %} The ID of the [Loyalty Program](/api/loyalty-programs) that the Promotion belongs to. - + {% /property %} - + {% property name="summary" type="string" %} The display summary for the Promotion. - + {% /property %} - + {% property name="mediaUploadId" type="string" %} The ID of the [Media Upload](/api/media-uploads/) image of the Promotion. - + {% /property %} - + {% property name="img" type="string" %} The img URL of the Promotion. - + {% /property %} - + {% property name="startsAt" type="timestamp" %} The timestamp of when the Promotion starts. - + {% /property %} - + {% property name="endsAt" type="timestamp" %} The timestamp of when the Promotion ends. - + {% /property %} - + {% property name="rewards" type="array" %} A list of [Rewards](/api/promotions#promotion-reward-model) that the account will receive upon completing the Promotion. - + {% /property %} - + {% property name="eventType" type="string" %} The [type of Event](/api/events) that will trigger increments and completions of the Promotion. - + {% /property %} - + {% property name="target" type="object" %} Describes how to complete the promotion. See [Promotion Target](/api/promotions#promotion-target-model). - + {% /property %} - + {% property name="type" type="string" %} The type of Promotion. Can be `cashback` or `challenge`. `challenge` rewards the account once, after the challenge target is met. `cashback` gives a reward based on the payment amount, which can be completed an unlimited number of times. - + {% /property %} - + {% property name="conditions" type="array" %} The list of [Conditions](/api/promotions#promotion-condition-model) that need to be met when incrementing/completing the Promotion. - + {% /property %} - + {% property name="description" type="string" %} Displayable description for the Promotion. - + {% /property %} - + {% property name="progress" type="number" %} The Account's progress towards completing the Promotion. - + {% /property %} - + {% property name="status" type="number" %} The status of the Promotion Membership. Can be "active", "expired", or "complete". - + {% /property %} - + {% property name="createdAt" type="string" %} The timestamp of when the Promotion Membership was created. - + {% /property %} - + {% property name="createdBy" type="crn" %} The User or API Key that created the Promotion Membership. - + {% /property %} - + {% property name="modifiedAt" type="string" %} The timestamp of when the Promotion Membership was last modified. - + {% /property %} - + {% property name="modifiedBy" type="crn" %} The User or API Key that last modified the Promotion Membership. - + {% /property %} - + {% property name="test" type="boolean" %} `true` if the promotion membership is for testing purposes only. - - + {% /property %} +{% /properties %} --- - - ## List Promotion Memberships by Account +%} + ## List Promotion Memberships by Account {% badge type="experimental" /%} Returns a [paginated](/api/pagination/) list of Promotion Memberships for an [Account](/api/accounts) - +{% /endpoint %} diff --git a/src/content/api/promotions.mdx b/src/content/api/promotions.mdoc similarity index 57% rename from src/content/api/promotions.mdx rename to src/content/api/promotions.mdoc index 9c9d8ecd7..70d0d55b7 100644 --- a/src/content/api/promotions.mdx +++ b/src/content/api/promotions.mdoc @@ -5,214 +5,208 @@ nav: path: Loyalty Programs order: 3 --- -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Endpoint from '../../components/Endpoint.astro'; -import Badge from '../../components/Badge.astro'; -import Error from '../../components/Error.astro'; - Promotions are a mechanism to reward accounts for completing certain actions. ## Promotion Model - - +{% properties %} + {% property name="id" type="string" %} The unique identifier for the Promotion. - + {% /property %} - + {% property name="accountId" type="string" %} The ID of the [Account](/api/accounts) that owns the Promotion. - + {% /property %} - + {% property name="name" type="string" %} The display name of the Promotion. - + {% /property %} - + {% property name="programId" type="string" %} The ID of the [Loyalty Program](/api/loyalty-programs) that the Promotion belongs to. - + {% /property %} - + {% property name="summary" type="string" %} The display summary for the Promotion. - + {% /property %} - + {% property name="mediaUploadId" type="string" %} The ID of the [Media Upload](/api/media-uploads/) image of the Promotion. - + {% /property %} - + {% property name="img" type="string" %} The img URL of the Promotion. - + {% /property %} - + {% property name="startsAt" type="timestamp" %} The timestamp of when the Promotion starts. - + {% /property %} - + {% property name="endsAt" type="timestamp" %} The timestamp of when the Promotion ends. - + {% /property %} - + {% property name="rewards" type="array" %} A list of [Rewards](/api/promotions#promotion-reward-model) that the account will receive upon completing the Promotion. - + {% /property %} - + {% property name="eventType" type="string" %} The [type of Event](/api/events) that will trigger increments and completions of the Promotion. - + {% /property %} - + {% property name="target" type="object" %} Describes how to complete the promotion. See [Promotion Target](/api/promotions#promotion-target-model). - + {% /property %} - + {% property name="type" type="string" %} The type of Promotion. Can be `cashback` or `challenge`. `challenge` rewards the account once, after the challenge target is met. `cashback` gives a reward based on the payment amount, which can be completed an unlimited number of times. - + {% /property %} - + {% property name="conditions" type="array" %} The list of [Conditions](/api/promotions#promotion-condition-model) that need to be met when incrementing/completing the Promotion. - + {% /property %} - + {% property name="description" type="string" %} Displayable description for the Promotion. - + {% /property %} - + {% property name="createdAt" type="string" %} The timestamp of when the Promotion was created. - + {% /property %} - + {% property name="createdBy" type="crn" %} The User or API Key that created the Promotion. - - + {% /property %} +{% /properties %} ## Promotion Target Model - - +{% properties %} + {% property name="type" type="string" %} Can be `count` or `sum`. `count` if the progress should be incremented by 1 each time. `sum` if the progress should be summed from the specified `field` property. - + {% /property %} - + {% property name="field" type="string" %} Only supplied if `type` is `sum`. This denotes which field to sum on the [Event](/api/events) to reach the target amount. - + {% /property %} - + {% property name="amount" type="number" %} The chosen number to reach for completion of the Promotion. - - + {% /property %} +{% /properties %} ## Promotion Reward Model - - +{% properties %} + {% property name="assetType" type="string" %} The [assetType](/api/asset-types) to reward. - + {% /property %} - + {% property name="collectionId" type="string" %} The ID of the [Token Collection](/api/tokens#token-collection-model) that should be rewarded. Only supplied if `assetType` is `centrapay.token.test` or `centrapay.token.main`. - + {% /property %} - + {% property name="name" type="string" %} The name of the [Token Collection](/api/tokens#token-collection-model) that is being rewarded. - + {% /property %} - + {% property name="img" type="string" %} The image of the [Token Collection](/api/tokens#token-collection-model) that is being rewarded. - + {% /property %} - + {% property name="amount" type="number" %} The amount of the chosen asset to reward. Only supplied if Promotion is type `challenge`. - + {% /property %} - + {% property name="exchangeRate" type="number" %} The rate of exchange from payment amount to reward. Only supplied if Promotion is type `cashback`. - - + {% /property %} +{% /properties %} ## Promotion Condition Model - - +{% properties %} + {% property name="field" type="string" %} The field to look at in the [Event](/api/events) object. - + {% /property %} - + {% property name="value" type="string" %} The value that the field must satisfy depending on the `operator`. - + {% /property %} - + {% property name="operator" type="string" %} The operator to use when looking at the value of the field. Can be `equals`, `not`, `greater-than`, `less-than`. - - + {% /property %} +{% /properties %} --- - - ## Create Promotion +%} + ## Create Promotion {% badge type="experimental" /%} - - + {% properties %} + {% property name="name" type="string" required=true %} The display name of the Promotion. - + {% /property %} - + {% property name="summary" type="string" %} The display summary for the Promotion. - + {% /property %} - + {% property name="mediaUploadId" type="string" %} The ID of the [Media Upload](/api/media-uploads/) image of the Promotion. - + {% /property %} - + {% property name="startsAt" type="timestamp" %} The timestamp of when the Promotion starts. - + {% /property %} - + {% property name="endsAt" type="timestamp" %} The timestamp of when the Promotion ends. - + {% /property %} - + {% property name="rewards" type="array" %} A list of [Rewards](/api/promotions#promotion-reward-model) that the account will receive upon completing the Promotion. - + {% /property %} - + {% property name="eventType" type="string" required=true %} The type of [Event](/api/events) that will trigger increments and completions of the Promotion. - + {% /property %} - + {% property name="target" type="object" %} Describes how to complete the promotion. See [Promotion Target](/api/promotions#promotion-target-model). Only supplied if `type` is `challenge`. - + {% /property %} - + {% property name="type" type="string" required=true %} The type of Promotion. Can be `cashback` or `challenge`. `challenge` rewards the account once, after the challenge target is met. `cashback` gives a reward based on the payment amount, which can be completed an unlimited number of times. - + {% /property %} - + {% property name="conditions" type="array" %} The list of [Conditions](/api/promotions#promotion-condition-model) that need to be met when incrementing/completing the Promotion. - + {% /property %} - + {% property name="description" type="string" %} Displayable description for the Promotion. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="PROMOTION_REWARDS_INVALID" %} One or more of the rewards ledgers does not exist or permissions are invalid. - - - + {% /error %} + {% /properties %} +{% /endpoint %} --- - - ## List Promotions by Account +%} + ## List Promotions by Account {% badge type="experimental" /%} Returns a [paginated](/api/pagination/) list of Promotions for an [Account](/api/accounts). - +{% /endpoint %} diff --git a/src/content/api/quotas.mdx b/src/content/api/quotas.mdoc similarity index 62% rename from src/content/api/quotas.mdx rename to src/content/api/quotas.mdoc index 7d733247a..b2918ff03 100644 --- a/src/content/api/quotas.mdx +++ b/src/content/api/quotas.mdoc @@ -5,42 +5,36 @@ nav: path: API order: 19 --- -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Badge from '../../components/Badge.astro'; -import Endpoint from '../../components/Endpoint.astro'; -import CodePanel from '../../components/CodePanel.astro'; - Centrapay account quotas are enforced on usage types such as spending or topping up, and may apply to a time period (daily, monthly, yearly). Account quotas may be affected by the verification status of the Centrapay account. ## Quota Model - - +{% properties %} + {% property name="type" type="string" %} The quota's type. See [Supported Quota Types](#supported-quota-types). - + {% /property %} - + {% property name="limit" type="bignumber" %} The quota's upper usage limit. - + {% /property %} - + {% property name="usage" type="bignumber" %} The quota's current usage. - + {% /property %} - + {% property name="assetType" type="string" %} The type of asset the quota is scoped to, eg `centrapay.nzd.main`. - + {% /property %} - + {% property name="period" type="string" %} The recurring, time-bound quota's duration: `daily`, `monthly` or `yearly`. - + {% /property %} - + {% property name="interval" type="string" %} The specific day, month or year the quota applies to, eg: `2020-01-01`, `2020-01`, `2020`. - - + {% /property %} +{% /properties %} ### Supported Quota Types @@ -51,11 +45,11 @@ Centrapay account quotas are enforced on usage types such as spending or topping --- - - ## Get Account Quotas +%} + ## Get Account Quotas {% badge type="experimental" /%} Retrieve quota limits and usages for the current intervals. Ie, all quotas for the current day, current month and current year as well as any quotas that are not associated with a temporal period. @@ -63,22 +57,19 @@ Centrapay account quotas are enforced on usage types such as spending or topping If a quota limit is exceeded by an action that enforces quota limits, an error response will be returned. The quotas field will contain all quota limits that are exceeded with the usage set to the amount that the quota would have been updated to if the action was completed. - - ```json title="Error Response" - { - "message": "QUOTA_EXCEEDED", - "quotas": [ - { - "limit": "9999", - "interval": "2021", - "period": "yearly", - "usage": "10000", - "type": "topup", - "assetType": "centrapay.nzd.main" - } - ] - } - ``` - - - + ```json + { + "message": "QUOTA_EXCEEDED", + "quotas": [ + { + "limit": "9999", + "interval": "2021", + "period": "yearly", + "usage": "10000", + "type": "topup", + "assetType": "centrapay.nzd.main" + } + ] + } + ``` +{% /endpoint %} diff --git a/src/content/api/scanned-codes.mdx b/src/content/api/scanned-codes.mdoc similarity index 54% rename from src/content/api/scanned-codes.mdx rename to src/content/api/scanned-codes.mdoc index 6e7fe2406..3054f3a5e 100644 --- a/src/content/api/scanned-codes.mdx +++ b/src/content/api/scanned-codes.mdoc @@ -5,73 +5,68 @@ nav: path: Scanned Codes order: 1 --- -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Error from '../../components/Error.astro'; -import Endpoint from '../../components/Endpoint.astro'; - A scanned code is a barcode that a merchant scans. The code can be used to create a [Payment Request](/api/payment-requests). ## Scanned Code Model - - +{% properties %} + {% property name="code" type="string" %} The utf8 representation of data decoded from what was scanned. - + {% /property %} - + {% property name="scannedBy" type="string" %} The party that scanned the code. Can be `merchant`. - + {% /property %} - + {% property name="provider" type="string" %} The integrator that owns the code. This can be used to calculate discounts on [Line Items](/api/payment-requests#line-item-model). Can be `paypal`, `venmo`, `farmlands` or `centrapay`. - + {% /property %} - + {% property name="displayName" type="string" %} A formatted name that can be displayed in a client. - + {% /property %} - + {% property name="merchantConfigId" type="string" %} The ID of the [Merchant Config](/api/merchant-configs). - - + {% /property %} +{% /properties %} --- - +%} ## Decode Scanned Code This endpoint allows you to decode a scanned code. - - + {% properties %} + {% property name="code" type="string" required=true %} The utf8 representation of data decoded from what was scanned. - + {% /property %} - + {% property name="scannedBy" type="string" required=true %} The party that scanned the code. Can be `merchant`. - + {% /property %} - + {% property name="merchantConfigId" type="string" required=true %} The ID of the [Merchant Config](/api/merchant-configs). - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="UNKNOWN_CODE" %} The code doesn’t exist or is no longer active in our system. - + {% /error %} - + {% error code="403" message="MERCHANT_CONFIG_NOT_FOUND" %} The supplied merchant config does not exist. - + {% /error %} - + {% error code="403" message="INVALID_MERCHANT_CONFIG" %} The merchant config does not have a payment option that can satisfy the scanned code. - - - + {% /error %} + {% /properties %} +{% /endpoint %} diff --git a/src/content/api/settlements.mdx b/src/content/api/settlements.mdoc similarity index 56% rename from src/content/api/settlements.mdx rename to src/content/api/settlements.mdoc index 0bbf77c5d..8bb996a83 100644 --- a/src/content/api/settlements.mdx +++ b/src/content/api/settlements.mdoc @@ -5,10 +5,6 @@ nav: path: API order: 21 --- -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Endpoint from '../../components/Endpoint.astro'; - A Settlement is created from completed [Payment Requests](/api/payment-requests/) over a specified period for each supported [Asset Type](/api/asset-types/) for each [Merchant](/api/merchants/). Settlements can only be created if the Merchant has a [Settlement Config](/api/merchants#settlement-config-model). @@ -18,63 +14,63 @@ Settlements can only be created if the Merchant has a [Settlement Config](/api/m ## Settlement Model - - +{% properties %} + {% property name="id" type="string" %} The unique identifier for the Settlement. - + {% /property %} - + {% property name="status" type="string" %} The status of the Settlement. - + {% /property %} - + {% property name="assetType" type="string" %} The [Asset Type](/api/asset-types/) being settled. - + {% /property %} - + {% property name="currency" type="string" %} The settlement currency. - + {% /property %} - + {% property name="createdAt" type="timestamp" %} When the Settlement was created. - + {% /property %} - + {% property name="createdBy" type="crn" %} The User or API Key that created the Settlement. - + {% /property %} - + {% property name="settledAt" type="timestamp" %} The time when settlement was completed. - + {% /property %} - + {% property name="settledBy" type="crn" %} The User or API Key that completed the Settlement. - + {% /property %} - + {% property name="settlementAmount" type="bignumber" %} The total amount of the settlement. - + {% /property %} - + {% property name="settlementBankAccountId" type="string" %} The ID of the [Bank Account](/api/bank-accounts/) used for settlement. - + {% /property %} - + {% property name="type" type="string" %} The type of the Settlement. - + {% /property %} - + {% property name="test" type="boolean" %} Flag indicating whether the Settlement is a test resource. - - + {% /property %} +{% /properties %} --- - +%} ## List Settlements This endpoint allows you to list Settlements. - +{% /endpoint %} diff --git a/src/content/api/tokens.mdx b/src/content/api/tokens.mdoc similarity index 53% rename from src/content/api/tokens.mdx rename to src/content/api/tokens.mdoc index f1464d188..431c11fb8 100644 --- a/src/content/api/tokens.mdx +++ b/src/content/api/tokens.mdoc @@ -5,12 +5,6 @@ nav: path: Assets order: 5 --- -import Properties from '../../components/Properties.astro'; -import Property from '../../components/Property.astro'; -import Error from '../../components/Error.astro'; -import Endpoint from '../../components/Endpoint.astro'; -import Badge from '../../components/Badge.astro'; - Tokens are [Assets](/api/assets/) which can only be spent in full. Every [Token](#token-model) is associated with a [Collection](#token-collection-model), which defines the branding and general rules for the Tokens, such as active duration. @@ -22,324 +16,323 @@ A [Redemption Condition](#redemption-condition-model) is created for each [Merch ## Token Collection Model - - +{% properties %} + {% property name="name" type="string" %} The display name of the Collection. - + {% /property %} - + {% property name="accountId" type="string" %} The [Account](/api/accounts/) that will own the Collection. - + {% /property %} - + {% property name="tokenExpiresAfter" type="object" %} The active duration of all Tokens created from this Collection. See [Token Expires After Model](#token-expires-after-model). - + {% /property %} - + {% property name="tokenExpiresAt" type="timestamp" %} A date that all tokens will expire on if they haven’t expired earlier. - + {% /property %} - + {% property name="type" type="string" required=true %} The type of value gained by redeeming Tokens. Valid values are `product` and `discount`. - + {% /property %} - - The maximum agreed value that any merchants will be settled for a Token redemption.
+ {% property name="maxValue" type="monetary" %} + The maximum agreed value that any merchants will be settled for a Token redemption. Required for Collections of type `discount`, where it defines the value that each Token will discount from a payment. - + {% /property %} - + {% property name="id" type="string" %} The unique identifier of the Token Collection. - + {% /property %} - + {% property name="test" type="boolean" %} `true` if the Token Collection is for testing purposes only. - + {% /property %} - + {% property name="status" type="string" %} The status of the Token Collection. Valid values: `active`. - + {% /property %} - + {% property name="createdAt" type="timestamp" %} Timestamp at which the Token Collection was created. - + {% /property %} - + {% property name="createdBy" type="crn" %} The identity that created the Token Collection. - + {% /property %} - + {% property name="mediaUploadId" type="string" %} The id of the [Media Upload](/api/media-uploads/) image of the Collection. - + {% /property %} - + {% property name="externalId" type="string" %} An identifier to associate the Collection with an external campaign or event. - + {% /property %} - + {% property name="img" type="string" %} The img URL of the Collection. - + {% /property %} - + {% property name="issuer" type="string" %} The name of the [Business](/api/businesses/) linked to the Account. - - + {% /property %} +{% /properties %} --- ## Token Expires After Model - - +{% properties %} + {% property name="period" type="string" required=true %} Supported values are `hour`, `day`, `week`, `month` and `year`. - + {% /property %} - + {% property name="duration" type="string" required=true %} Number of `period` until token expiration. - + {% /property %} - + {% property name="ceil" type="string" %} Interval to round token expiry up to. Supported values are `hour`, `day`, `week`, `month` and `year`. - - + {% /property %} +{% /properties %} --- -## Redemption Condition Model +## Redemption Condition Model {% badge type="experimental" /%} - - +{% properties %} + {% property name="merchantId" type="string" %} The identifier of the [Merchant](/api/merchants) that is accepting the collection. - + {% /property %} - + {% property name="allowedProducts" type="object" %} List of [Allowed Products](#allowed-products-model). Required for collections of type `product`. - + {% /property %} - + {% property name="id" type="string" %} The unique identifier of the Redemption Condition. - + {% /property %} - + {% property name="collectionId" type="string" %} The [Token Collection](#token-collection-model) that will govern the branding and redemption rules for the Token. - + {% /property %} - + {% property name="createdAt" type="timestamp" %} Timestamp at which the Redemption Condition was created. - + {% /property %} - + {% property name="createdBy" type="crn" %} The identity that created the activity. - - + {% /property %} +{% /properties %} --- -## Allowed Products Model +## Allowed Products Model {% badge type="experimental" /%} - - +{% properties %} + {% property name="sku" type="string" %} The SKU of the product that is to be accepted. - + {% /property %} - + {% property name="name" type="string" %} Display name of the product. - + {% /property %} - + {% property name="maxValue" type="monetary" %} The maximum value that the product can be redeemed for. - - + {% /property %} +{% /properties %} --- -## Token Model +## Token Model {% badge type="experimental" /%} - - +{% properties %} + {% property name="collectionId" type="string" %} The [Token Collection](#token-collection-model) that will govern the branding and redemption rules for the token. - + {% /property %} - + {% property name="idempotencyKey" type="string" %} Client-supplied identifier that prevents double creation. - + {% /property %} - + {% property name="externalId" type="string" %} The asset identifier from the issuing system. - + {% /property %} - + {% property name="accountId" type="string" %} The Account to create the token for. Defaults to the Account on the Token Collection. - - + {% /property %} +{% /properties %} --- - - ## Create Token Collection +%} + ## Create Token Collection {% badge type="experimental" /%} This endpoint allows you to create a [Token Collection](#token-collection-model). - - + {% properties %} + {% property name="name" type="string" required=true %} The display name of the Collection. - + {% /property %} - + {% property name="accountId" type="string" required=true %} The [Account](/api/accounts/) that will own the Collection. - + {% /property %} - + {% property name="tokenExpiresAfter" type="object" %} The active duration of all Tokens created from this Collection. See [Token Expires After Model](#token-expires-after-model). - + {% /property %} - + {% property name="tokenExpiresAt" type="timestamp" %} A date that all tokens will expire on if they haven’t expired earlier. - + {% /property %} - + {% property name="type" type="string" required=true %} The type of value gained by redeeming Tokens. Valid values are `product` and `discount`. - + {% /property %} - - The maximum agreed value that any merchants will be settled for a Token redemption.
- Required for Collections of type `discount`, where it defines the value that each Token will discount from a payment. - + {% property name="maxValue" type="monetary" %} + The maximum agreed value that any merchants will be settled for a Token redemption. Required for Collections of type `discount`, where it defines the value that each Token will discount from a payment. + {% /property %} - + {% property name="mediaUploadId" type="string" %} The id of the [Media Upload](/api/media-uploads/) image of the Collection. - + {% /property %} - + {% property name="externalId" type="string" %} An identifier to associate the Collection with an external campaign or event. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="EXTERNAL_ID_ALREADY_USED" %} A collection has already been created for this account with the given externalId. - - + {% /error %} + {% /properties %} - +{% /endpoint %} --- - - ## List Token Collections +%} + ## List Token Collections {% badge type="experimental" /%} Returns a [paginated](/api/pagination/) list of [Token Collections](#token-collection-model) for an Account. - - + {% properties %} + {% property name="pageKey" type="string" %} Used to retrieve the next page of items. - - - + {% /property %} + {% /properties %} +{% /endpoint %} --- - - ## Create Redemption Condition +%} + ## Create Redemption Condition {% badge type="experimental" /%} This endpoint allows you to create a [Redemption Condition](#redemption-condition-model). - - + {% properties %} + {% property name="merchantId" type="string" required=true %} The identifier of the [Merchant](/api/merchants) that is accepting the collection. - + {% /property %} - + {% property name="allowedProducts" type="object" required=true %} List of [Allowed Products](#allowed-products-model). Required for collections of type `product`. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="INVALID_AMOUNT" %} One or more of the maxValue amount in the products has exceeded the maxValue amount defined on the collection. - + {% /error %} - + {% error code="403" message="REDEMPTION_CONDITION_ALREADY_EXISTS" %} A redemption condition for the collection and the merchant has already been created. - - + {% /error %} + {% /properties %} - +{% /endpoint %} --- - - ## Set Allowed Products for Redemption Condition +%} + ## Set Allowed Products for Redemption Condition {% badge type="experimental" /%} This endpoint allows you to set [Allowed Products](#allowed-products-model) for a [Redemption Condition](#redemption-condition-model). - - + {% properties %} + {% property name="allowedProducts" type="object" required=true %} List of [Allowed Products](#allowed-products-model). Required for collections of type `product`. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="INVALID_AMOUNT" %} One or more of the maxValue amount in the products has exceeded the maxValue amount defined on the collection. - + {% /error %} - - + {% /properties %} +{% /endpoint %} -- - - ## Create Token +%} + ## Create Token {% badge type="experimental" /%} This endpoint allows you to create a Token. - - + {% properties %} + {% property name="collectionId" type="string" required=true %} The [Token Collection](#token-collection-model) that will govern the branding and redemption rules for the token. Currently only Collections of type `product` are supported. - + {% /property %} - + {% property name="idempotencyKey" type="string" required=true %} Client-supplied identifier that prevents double creation. - + {% /property %} - + {% property name="externalId" type="string" %} The asset identifier from the issuing system. - + {% /property %} - + {% property name="accountId" type="string" %} The Account to create the token for. Defaults to the Account on the Token Collection. - - + {% /property %} + {% /properties %} - - + {% properties heading="Errors" %} + {% error code="403" message="TOKEN_ALREADY_CREATED" %} Token with supplied parameters already exists. - + {% /error %} - + {% error code="403" message="LIVENESS_MISMATCH" %} The account is test and the collection's liveness is main or vice versa. - - - + {% /error %} + {% /properties %} +{% /endpoint %}