Download OpenAPI specification:Download
Open Fabric APIs, v1
Our APIs use an authentication scheme based on OAuth 2.0. See Authentication for more details.
| grant_type required | string Value: "client_credentials" |
| scope | string Space-separated API scopes for the token. See API Access Scopes for the list of available scopes. If not provided, the access token will be generated with all scopes. |
grant_type=client_credentials&scope=txn.c%20txn.r
{- "access_token": "eyJz9sdfsdfsdfsd",
- "id_token": "dmcxd329ujdmkemkd349r",
- "token_type": "Bearer",
- "expires_in": 3600
}API used to provision new accounts. See Provision account for more details.
This API can be used to provision a new account, virtual card or physical card.
See Own App Tokens, Digital Wallet Tokens, Virtual Cards or Physical Cards for more details.
| Idempotency-Key | string Unique value submitted by the partner to ensure idempotent request during provisioning. |
| type | string (PbaProvisionType) Enum: "nfc_device_token" "static_token" "push_provision" "physical_card"
|
| payment_network | string (PbaPaymentNetwork) Enum: "mastercard" "visa" The payment network of the transaction |
| tenant_customer_ref required | string Customer identifier in your system |
| tenant_account_ref required | string <= 64 characters Account identifier of the customer in your system. It is strongly recommended to limit the length of this field to 26 characters or less. Longer values may trigger an error while provisioning depending on the card network configuration. |
| tenant_token_ref | string Token identifier in your system. Required if Idempotency-Key is not set. If set, this will be passed to card network as the issuer token identifier. If not set, the Idempotency-Key will be used instead. |
| wallet_id | string Secure device wallet identifier. Required for Own App Tokens. Can be obtained by reading |
| device_name | string Name of the device |
| tenant_account_device_ref | string <= 32 characters Device identifier in your system |
| billing_currency | string = 3 characters ^[A-Z]*$ Billing currency (ISO 4217 currency code). If not passed, the default billing currency will be used. |
object (Address) | |
| instrument | string (PbaProvisionInstrument) Enum: "manual_card_entry" "google_pay" "samsung_pay" "apple_pay"
|
| card_name | string Name of the card |
| card_program_id | string <uuid> Card Program identifier. If not provided, the default card program will be used. |
| printed_name | string [ 1 .. 26 ] characters Name to emboss on the card. Required when |
object Delivery address of the card. Required when |
{- "type": "static_token",
- "tenant_customer_ref": "customer-00000000000001",
- "tenant_account_ref": "FR00000000000001",
- "tenant_token_ref": "TOK000000000000001",
- "card_program_id": "3c1e7a52-8f4b-4d2a-9e6f-1b2c3d4e5f60"
}{- "tenant_account_ref": "FR00000000000001",
- "tenant_customer_ref": "customer-00000000000001",
- "of_customer_id": "40095c2f-d391-4e06-94d9-cf0b3191c548",
- "of_account_id": "5bafb9bc-9573-4acf-b686-04bf62c81af8",
- "customer_id": "40095c2f-d391-4e06-94d9-cf0b3191c548",
- "account_id": "5bafb9bc-9573-4acf-b686-04bf62c81af8",
- "static_token_id": "180106f9-8177-42fa-99bf-23ae8d785636",
- "instrument": "manual_card_entry",
- "status": "active",
- "locked": false,
- "created_at": "2026-03-10T10:27:58.253Z",
- "updated_at": "2026-03-10T10:27:58.253Z"
}Activate a digital token server-side, called by your backend. The token is
identified by tsp_token_ref (the TSP token reference).
| tenant_account_ref required | string Account identifier of the customer in your system. |
| tenant_token_ref | string Optional token identifier in your system. |
| tsp_token_ref required | string TSP token reference (e.g. the Mastercard Token Unique Reference) to activate. |
| activation_mode | string (ActivationMode) Enum: "tav" "customer_service" Token activation mode.
|
| reason_code | string Activation reason code forwarded to the network (Customer Service API). |
{- "tenant_account_ref": "string",
- "tenant_token_ref": "string",
- "tsp_token_ref": "string",
- "activation_mode": "tav",
- "reason_code": "string"
}{- "success": true,
- "activation_mode": "tav",
- "activation_data": "string"
}This API can be used to provision an account for an existing card.
See Own App Tokens - Tokenize an existing card for more details.
| digital_wallet required | string (DigitalWallet) Enum: "issuer" "google_pay" "apple_pay" "samsung_pay" Digital wallet provider. Use |
| tenant_customer_ref required | string Customer identifier in your system |
| issuer_card_id required | string Issuer card identifier retrieved from your CMS |
| wallet_id required | string Secure device wallet identifier |
| issuer_authentication_data | string Issuer authentication value to be used in the tokenization request with the token service provider (TSP). The authentication value is specific to the token service provider (TSP), and it should be PGP-encrypted with Open Fabric’s shared public key, Base64-encoded when sending to Open Fabric |
| encrypted_card_data required | string Card data JSON encrypted with Open Fabric’s shared public key, Base64-encoded |
object (Address) |
{- "digital_wallet": "issuer",
- "tenant_customer_ref": "customer-00000000000001",
- "issuer_card_id": "507e8c90-3cfc-44ee-b701-0630067eb44fa5e9351a-0a6",
- "wallet_id": "507e8c90-3cfc-44ee-b701-0630067eb44fa5e9351a-0a6",
- "encrypted_card_data": "eyJ4NWMiOlsiTUlJQzNqQ0NBY2FnQXdJQkFnSUpBT1FDdnc2..."
}{- "wallet_id": "507e8c90-3cfc-44ee-b701-0630067eb44fa5e9351a-0a6",
- "provisioning_data": {
- "opc": "eyJ4NWMiOlsiTUlJQzNqQ0NBY2FnQXdJQkFnSUpBT1FDdnc2..."
}
}APIs used to manage the lifecycle of secure device wallets. See Lifecycle management for more details.
You can use this API to lock a secure device wallet. This will temporarily block payments and other functionalities of the wallet.
| id required | string <uuid> Secure device wallet identifier |
| reason_code required | string (PbaLockWalletReasonCode) Enum: "device_stolen" "device_lost" "suspected_fraud" "other" |
| reason required | string Reason for changing the status |
{- "reason_code": "suspected_fraud",
- "reason": "Requested by fraud team"
}{- "wallet_id": "6d6a9511-c4d3-4bc0-8d02-a054e8a5559112d56356-efa",
- "status": "suspended",
- "status_timestamp": "2026-03-17T12:00:00.000Z",
- "suspended_by": [
- "TOKEN_REQUESTOR"
]
}You can use this API to unlock a secure device wallet.
| id required | string <uuid> Secure device wallet identifier |
| reason_code required | string (PbaUnlockWalletReasonCode) Enum: "device_found" "not_fraud" "other" |
| reason required | string Reason for changing the status |
{- "reason_code": "not_fraud",
- "reason": "Customer has been verified by fraud team"
}{- "wallet_id": "6d6a9511-c4d3-4bc0-8d02-a054e8a5559112d56356-efa",
- "status": "active",
- "status_timestamp": "2026-03-17T12:00:00.000Z",
- "suspended_by": [ ]
}You can use this API to delete a secure device wallet.
Warning A secure device wallet deletion cannot be undone.
| id required | string <uuid> Secure device wallet identifier |
| reason_code required | string (PbaLockWalletReasonCode) Enum: "device_stolen" "device_lost" "suspected_fraud" "other" |
| reason required | string Reason for changing the status |
{- "reason_code": "device_stolen",
- "reason": "Requested by fraud team"
}{- "wallet_id": "6d6a9511-c4d3-4bc0-8d02-a054e8a5559112d56356-efa",
- "status": "deactivated",
- "status_timestamp": "2026-03-17T12:00:00.000Z",
- "suspended_by": [ ]
}APIs used to retrieve sensitive virtual card details. See Display card details for more details.
This API can be used to get a card fetch token for a specific virtual card.
| static_token_id required | string <uuid> Open Fabric's static token id for the card. |
| account_id required | string Account identifier in Open Fabric.
Must match the |
| card_encryption_key | string The public key (PEM format) to be used when encrypting the card detail. When this field is not specified, no encryption will be performed to secure the card detail. |
| card_encryption_algo | string (CardEncryptionAlgo) Enum: "rsa_oaep" "ecc_ecies" "ecdh" The algorithm to be used when encrypting the card detail.
If specified, you must send the value of the public key file (PEM format) in the |
{- "static_token_id": "c2319421-f0e8-4dd6-a099-124c5a3c6592",
- "account_id": "436605a1-271d-49a7-80f0-bcaf095cdd6a",
- "card_encryption_key": "-----BEGIN PUBLIC KEY-----\nMII…\n-----END PUBLIC KEY-----",
- "card_encryption_algo": "rsa_oaep"
}{- "card_fetch_token": "eyJhbGciOiJIUzI1...adQssw5c"
}This API can be used to retrieve sensitive details of a virtual card.
Warning Please be aware that your system might be subject to a higher level of PCI DSS certification if you use this API.
| card_fetch_token required | string The card fetch token obtained using the Get card fetch token request |
| fetch_cvv | boolean Default: true It will be used to return cvv in response or not. By default its true |
{- "card_fetch_token": "YTZkYmJkYWItMWI3ZC00MzNhLTkzOWEtZjYzYzkwMjJmODMz"
}{- "provider": "mastercard",
- "card_reference_id": "dpan_9ku2ouUwBCHW3pYSevRE72XD5kYGSQfMKuhBjWLkqAue_2Eu6hV4BwMfng",
- "card_number": "5281724086788282",
- "redacted_number": "XXXXXXXXXXXX8282",
- "cvv": "111",
- "expiry_month": "12",
- "expiry_year": "25",
- "message": ""
}APIs used to display virtual and physical card details securely. See Display virtual cards and Set up the Card SDK for more details.
Creates a single-use session_init_token for a customer, which your app uses to start a Card SDK session. Call this API from your backend, never from your app. See Set up the Card SDK for more details.
Requires cards.read. Each operation in operations also needs its own scope: CARD_LIST, CARD_GET and PAN_REVEAL need cards.read; CARD_UPDATE needs tokens.update; PIN_REVEAL needs pin.read; PIN_CHANGE needs pin.update. Requesting an operation without its scope returns 403. When operations is left out, the session gets the operations your scopes allow.
| X-Instrumentation | string Source of the request |
| customer_id required | string Customer identifier in Open Fabric. |
| operations | Array of strings (SecureCardOperation) Items Enum: "CARD_LIST" "CARD_GET" "CARD_UPDATE" "PAN_REVEAL" "PIN_CHANGE" "PIN_REVEAL" Subset of the operations to grant. Omit to grant all operations your access token's scopes allow. |
| card_programs | Array of strings <uuid> [ items <uuid > ] Optionally binds the session to specific card programs; cards outside them are not visible. |
| ttl | integer [ 60 .. 3600 ] Default: 900 Session lifetime in seconds. |
| channel required | string (SecureCardChannel) Enum: "web" "android" The platform the Card SDK session is created for. |
| allowed_origin | string The embedding origin the session is pinned to. Required for |
{- "customer_id": "string",
- "operations": [
- "CARD_LIST"
], - "card_programs": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "ttl": 900,
- "channel": "web",
- "allowed_origin": "string"
}{- "session_init_token": "string",
- "expires_at": "2019-08-24T14:15:22Z"
}Generates a short-lived widget URL for displaying card details (PAN, expiry, CVV) in an iframe or webview. The widget URL is time-limited and single-use.
| static_token_id | string Either |
| card_fetch_token | string Either |
| card_art_asset_id | string <uuid> Identifier of a pre-uploaded card art asset. Obtained from the asset upload API. Mutually exclusive with |
| card_art_base64 | string <= 204800 characters Base64 encoded card art image. Max 150KB decoded. Recommended dimensions: 340x214px (1.586:1) for a Mutually exclusive with |
| card_art_content_type | string (CardArtContentType) Enum: "image/png" "image/jpeg" "image/webp" MIME type of the card art image |
| text_color | string^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$ Hex color code for text displayed on the card widget (e.g., "#FFFFFF" for white). Optional, defaults to black if not provided. |
| orientation | string (CardWidgetOrientation) Enum: "horizontal" "vertical" Layout of the card widget. Optional, defaults to
|
{- "card_fetch_token": "eyJhbGciOiJIUzI1...",
- "card_art_asset_id": "7f3a2b1c-9d4e-5f6a-8b7c-0d1e2f3a4b5c"
}{- "expired_at": "2019-08-24T14:15:22Z"
}Uploads a card art image for reuse across multiple widget sessions. Returns an asset_id that can be referenced in the widget creation API.
| card_art_base64 required | string <= 204800 characters Base64 encoded card art image. Max 150KB decoded. Recommended dimensions: 340x214px (1.586:1) for a |
| card_art_content_type required | string (CardArtContentType) Enum: "image/png" "image/jpeg" "image/webp" MIME type of the card art image |
| card_art_asset_name | string Optional human-readable label for the asset (e.g., "Premium Black", "Student Card"). |
{- "card_art_base64": "iVBORw0KGgoAAAANSUhEUgAAAVQAAADW...",
- "card_art_content_type": "image/png",
- "card_art_asset_name": "Premium Black"
}{- "card_art_asset_id": "f202723b-2873-4618-a10b-6cec3b9c52f7",
- "card_art_asset_name": "Premium Black",
- "card_art_content_type": "image/png",
- "size_bytes": 6988,
- "created_at": "2026-03-16T09:23:48.684Z",
- "updated_at": "2026-03-16T09:23:48.684Z"
}Returns the card art assets uploaded by the tenant. Without limit or cursor, all assets are returned. To page, pass limit, then pass next_cursor from the response as cursor to fetch the next page.
| limit | integer [ 1 .. 50 ] Number of assets per page. When |
| cursor | string The |
{- "data": [
- {
- "card_art_asset_id": "f202723b-2873-4618-a10b-6cec3b9c52f7",
- "card_art_asset_name": "Premium Black",
- "card_art_content_type": "image/png",
- "size_bytes": 6988,
- "created_at": "2026-03-16T09:23:48.684Z"
}
]
}Returns one card art asset uploaded by the tenant.
| asset_id required | string <uuid> Identifier of card art asset. |
{- "card_art_asset_id": "f202723b-2873-4618-a10b-6cec3b9c52f7",
- "card_art_asset_name": "Premium Black",
- "card_art_content_type": "image/png",
- "size_bytes": 6988,
- "created_at": "2026-03-16T09:23:48.684Z",
- "updated_at": "2026-03-16T09:23:48.684Z"
}Renames a card art asset or replaces its image. The asset keeps its id and URL.
| asset_id required | string <uuid> Identifier of card art asset. |
| card_art_asset_name | string <= 100 characters New human-readable label for the asset. |
| card_art_base64 | string <= 204800 characters Base64 encoded replacement image. Send together with Max 150KB decoded. Recommended dimensions: 340x214px (1.586:1) for a |
| card_art_content_type | string (CardArtContentType) Enum: "image/png" "image/jpeg" "image/webp" MIME type of the card art image |
{- "card_art_asset_name": "string",
- "card_art_base64": "string",
- "card_art_content_type": "image/png"
}{- "card_art_asset_id": "f202723b-2873-4618-a10b-6cec3b9c52f7",
- "card_art_asset_name": "Premium Black",
- "card_art_content_type": "image/png",
- "size_bytes": 6988,
- "created_at": "2026-03-16T09:23:48.684Z",
- "updated_at": "2026-03-16T09:23:48.684Z"
}Deletes a previously uploaded card art asset. Existing widget sessions that already resolved this asset are unaffected.
| asset_id required | string <uuid> Identifier of card art asset. |
{- "error_code": "string",
- "message": "string",
- "details": [
- {
- "error_code": "string",
- "message": "string",
- "param": "string",
- "reason_code": "string",
- "reason": "string"
}
]
}APIs used to manage both virtual and physical cards. See Manage virtual cards and Manage physical cards for more details.
This API can be used to list all cards (virtual and physical) belonging to a customer.
Use the type filter to return only virtual cards (static_token) or only physical cards
(physical_card).
| tenant_customer_ref | string Filter by tenant customer ref |
| tenant_account_ref | string Filter by tenant account ref |
| instrument | string (RoutingDataInitializingInstrument) Enum: "web_checkout" "unilateral_checkout" "one_click_checkout" "recurring" "tenant_recurring" "pba_static_token" "qrph" "sgqr" "vietqr" "tap_and_pay" "manual_card_entry" "google_pay" "samsung_pay" "apple_pay" "in_app_shopping" Deprecated. Use |
| type | string (StaticTokenType) Enum: "static_token" "physical_card" Filter by static token type ( |
| status | string (StaticTokenStatus) Enum: "active" "inactive" "deactivated" Filter by status |
| locked | boolean Filter by lock status |
{- "data": [
- {
- "id": "4fbc4775-466c-4d21-bb8c-95f3ef9ffbea",
- "tenant_account_ref": "FR00000000000001",
- "tenant_customer_ref": "customer-00000000000001",
- "tenant_token_ref": "TOK000000000000001",
- "tsp_token_ref": "DWSPMC000000000132d72d4fcb2f4136a0532d3093ff1a45",
- "account_id": "c6045eed-b5cb-48f0-8321-b924a8e8f808",
- "customer_id": "5b3aae19-16b5-4aca-81b5-5d72a168c496",
- "dpan_redacted_number": "512*********9708",
- "dpan_expiry": {
- "month": 11,
- "year": 25
}, - "instrument": "manual_card_entry",
- "status": "active",
- "locked": false,
- "created_at": "2026-03-16T07:39:09.317Z",
- "updated_at": "2026-03-16T07:39:09.317Z"
}
]
}This API can be used to get details of a specific card.
| id required | string Static token identifier in Open Fabric representing a Virtual Card |
{- "id": "4fbc4775-466c-4d21-bb8c-95f3ef9ffbea",
- "tenant_account_ref": "FR00000000000001",
- "tenant_customer_ref": "customer-00000000000001",
- "tenant_token_ref": "TOK000000000000001",
- "tsp_token_ref": "DWSPMC000000000132d72d4fcb2f4136a0532d3093ff1a45",
- "account_id": "c6045eed-b5cb-48f0-8321-b924a8e8f808",
- "customer_id": "5b3aae19-16b5-4aca-81b5-5d72a168c496",
- "dpan_redacted_number": "512*********9708",
- "dpan_expiry": {
- "month": 11,
- "year": 25
}, - "instrument": "manual_card_entry",
- "status": "active",
- "locked": false,
- "created_at": "2026-03-16T07:39:09.317Z",
- "updated_at": "2026-03-16T07:39:09.317Z"
}This API can be used to lock or unlock a specific card. You receive a v1:card:locked or
v1:card:unlocked notification when the lock changes. A physical card that is not yet activated
can also be locked, for example so that it can be deleted. Locking a card here and locking it with
the Card SDK change the same lock.
| id required | string Static token identifier in Open Fabric representing a Virtual Card |
| lock_status required | string (StaticTokenLockStatus) Enum: "locked" "unlocked" |
| reason_code | string (StaticTokenCardReasonCode) Enum: "card_lost" "card_stolen" "card_found" "suspected_fraud" "not_fraud" "other" Why a card is locked or unlocked. Lock reasons: card_lost, card_stolen, suspected_fraud, other. Unlock reasons: card_found, not_fraud, other. The same values as the Card SDK's LockReason / UnlockReason, so a lock from your backend and a lock from the cardholder's app carry the same reason. A reason that does not fit the direction (e.g. card_found on a lock) is sent as other. |
| reason_text | string |
{- "lock_status": "locked"
}{- "id": "4fbc4775-466c-4d21-bb8c-95f3ef9ffbea",
- "tenant_account_ref": "FR00000000000001",
- "tenant_customer_ref": "customer-00000000000001",
- "tenant_token_ref": "TOK000000000000001",
- "tsp_token_ref": "DWSPMC000000000132d72d4fcb2f4136a0532d3093ff1a45",
- "account_id": "c6045eed-b5cb-48f0-8321-b924a8e8f808",
- "customer_id": "5b3aae19-16b5-4aca-81b5-5d72a168c496",
- "dpan_redacted_number": "512*********9708",
- "dpan_expiry": {
- "month": 11,
- "year": 25
}, - "instrument": "manual_card_entry",
- "status": "active",
- "locked": true,
- "created_at": "2026-03-16T07:39:09.317Z",
- "updated_at": "2026-03-16T07:39:09.317Z"
}This API can be used to deactivate a specific card.
Warning This action is permanent (cannot be undone) and requires the card to be locked first before deleting.
| id required | string Static token identifier in Open Fabric representing a Virtual Card |
| reason_text | string |
| reason_code | string (PbaCustomerDpanSuspendReasonCode) Enum: "device_lost" "device_stolen" "suspected_fraud" "other" |
{- "reason_text": "Customer reported device is lost",
- "reason_code": "device_lost"
}{- "id": "4fbc4775-466c-4d21-bb8c-95f3ef9ffbea",
- "tenant_account_ref": "FR00000000000001",
- "tenant_customer_ref": "customer-00000000000001",
- "tenant_token_ref": "TOK000000000000001",
- "tsp_token_ref": "DWSPMC000000000132d72d4fcb2f4136a0532d3093ff1a45",
- "account_id": "c6045eed-b5cb-48f0-8321-b924a8e8f808",
- "customer_id": "5b3aae19-16b5-4aca-81b5-5d72a168c496",
- "dpan_redacted_number": "512*********9708",
- "dpan_expiry": {
- "month": 11,
- "year": 25
}, - "instrument": "manual_card_entry",
- "status": "deactivated",
- "locked": true,
- "created_at": "2026-03-16T07:39:09.317Z",
- "updated_at": "2026-03-16T07:39:09.317Z"
}Activates a physical card. Physical cards are created with status inactive and are never
activated automatically. Call this API once the cardholder has received the card.
The card can only be activated once provisioning_status is completed. If a renewal is pending,
the new expiry date is applied on activation and fpan_expiry is updated. A locked card can be
activated; it stays locked.
| id required | string Static token identifier in Open Fabric representing a physical card |
{- "id": "string",
- "tenant_account_ref": "string",
- "tenant_customer_ref": "string",
- "tenant_token_ref": "string",
- "tsp_token_ref": "string",
- "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
- "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
- "dpan_redacted_number": "string",
- "dpan_expiry": {
- "month": "string",
- "year": "string"
}, - "fpan_redacted_number": "string",
- "fpan_expiry": {
- "month": "string",
- "year": "string"
}, - "card_id": "66f6e46c-f6a1-4af8-a1bd-49666bc01304",
- "instrument": "web_checkout",
- "status": "active",
- "locked": true,
- "card_program_id": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "type": "static_token",
- "provisioning_status": "enrollment_pending",
- "physical_card": {
- "printed_name": "string",
- "shipping_address": {
- "line1": "string",
- "line2": "string",
- "city": "string",
- "state": "string",
- "postal_code": "string",
- "country_code": "st"
}, - "fulfilment_status": "created",
- "pending_renewal": {
- "expiry_month": "st",
- "expiry_year": "st"
}, - "failure_reason": "string"
}
}Reissues a physical card's plastic on the same card number. Physical cards only.
reason: expiry (default) records a renewal with a new expiry date. The card keeps working; the new
expiry is returned as physical_card.pending_renewal and applied when the renewed card is activated.reason: replacement reprints a broken or worn card with the same card number and expiry. The card
stops working at once and works again when the new plastic is activated. Repeating the request while
the replacement is pending returns the same pending replacement.| id required | string Static token identifier in Open Fabric representing a physical card |
| reason | string Enum: "expiry" "replacement"
|
| expiry_month | string = 2 characters ^(0[1-9]|1[0-2])$ New two-digit expiry month, 01-12. Required for |
| expiry_year | string = 2 characters ^\d{2}$ New two-digit expiry year (YY). Required for |
{- "reason": "expiry",
- "expiry_month": "st",
- "expiry_year": "st"
}{- "id": "string",
- "tenant_account_ref": "string",
- "tenant_customer_ref": "string",
- "tenant_token_ref": "string",
- "tsp_token_ref": "string",
- "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
- "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
- "dpan_redacted_number": "string",
- "dpan_expiry": {
- "month": "string",
- "year": "string"
}, - "fpan_redacted_number": "string",
- "fpan_expiry": {
- "month": "string",
- "year": "string"
}, - "card_id": "66f6e46c-f6a1-4af8-a1bd-49666bc01304",
- "instrument": "web_checkout",
- "status": "active",
- "locked": true,
- "card_program_id": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "type": "static_token",
- "provisioning_status": "enrollment_pending",
- "physical_card": {
- "printed_name": "string",
- "shipping_address": {
- "line1": "string",
- "line2": "string",
- "city": "string",
- "state": "string",
- "postal_code": "string",
- "country_code": "st"
}, - "fulfilment_status": "created",
- "pending_renewal": {
- "expiry_month": "st",
- "expiry_year": "st"
}, - "failure_reason": "string"
}
}Notifications sent to your backend when tokens change state within a secure device wallet or when a tokenized transaction authorization occurs within the wallet.
See Token update notifications for more details.
This notification is sent when an account or card was successfully tokenized and activated in the secure device wallet.
| notification_id required | string <uuid> The unique identifier for the notification |
| type required | string Value: "v1:wallet:token:activated" |
| created_at required | string <date-time> The creation timestamp of the notification in ISO 8601 format |
required | object (WalletTokenActivatedEventNotificationPayload) Base schema for wallet token status change notifications data |
{- "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
- "type": "v1:wallet:token:activated",
- "created_at": "2019-08-24T14:15:22Z",
- "data": {
- "token_unique_reference": "string",
- "wallet_id": "string",
- "token_source": "financial_account",
- "card_program_id": "acba91e4-3ccc-44c0-89f3-673de52e33aa",
- "activated_at": "2019-08-24T14:15:22Z"
}
}This notification is sent when the tokenized account or card is suspended in the secure device wallet.
| notification_id required | string <uuid> The unique identifier for the notification |
| type required | string Value: "v1:wallet:token:suspended" |
| created_at required | string <date-time> The creation timestamp of the notification in ISO 8601 format |
required | object (WalletTokenSuspendedEventNotificationPayload) Base schema for wallet token status change notifications data |
{- "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
- "type": "v1:wallet:token:suspended",
- "created_at": "2019-08-24T14:15:22Z",
- "data": {
- "token_unique_reference": "string",
- "wallet_id": "string",
- "token_source": "financial_account",
- "card_program_id": "acba91e4-3ccc-44c0-89f3-673de52e33aa",
- "reason_code": "string",
- "reason": "string",
- "suspended_at": "2019-08-24T14:15:22Z"
}
}This notification is sent when the tokenized account or card is deleted from the secure device wallet.
| notification_id required | string <uuid> The unique identifier for the notification |
| type required | string Value: "v1:wallet:token:deleted" |
| created_at required | string <date-time> The creation timestamp of the notification in ISO 8601 format |
required | object (WalletTokenDeletedEventNotificationPayload) Base schema for wallet token status change notifications data |
{- "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
- "type": "v1:wallet:token:deleted",
- "created_at": "2019-08-24T14:15:22Z",
- "data": {
- "token_unique_reference": "string",
- "wallet_id": "string",
- "token_source": "financial_account",
- "card_program_id": "acba91e4-3ccc-44c0-89f3-673de52e33aa",
- "reason_code": "string",
- "reason": "string",
- "deleted_at": "2019-08-24T14:15:22Z"
}
}This notification is sent when a transaction is authorized within the secure device wallet.
| notification_id required | string <uuid> The unique identifier for the notification |
| type required | string Value: "v1:wallet:transaction:authorization" |
| created_at required | string <date-time> The creation timestamp of the notification in ISO 8601 format |
required | object (PbaWalletTransactionAuthorizedNotification) v1:wallet:transaction:authorization |
{- "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
- "type": "v1:wallet:transaction:authorization",
- "created_at": "2019-08-24T14:15:22Z",
- "data": {
- "id": "string",
- "tenant_id": "string",
- "wallet_id": "string",
- "token_unique_reference": "string",
- "tsp_transaction_ref": "string",
- "amount": 0,
- "currency": "string",
- "authorization_status": "authorized",
- "transaction_type": "purchase",
- "merchant_name": "string",
- "merchant_category_code": "string",
- "merchant_outlet_address": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "card_program_id": "acba91e4-3ccc-44c0-89f3-673de52e33aa"
}
}Notifications sent to your backend when a card is created, activated, updated, locked, unlocked or deactivated.
See Manage physical cards for more details.
This notification is sent when a new card has been created. A new card always has status inactive until it is activated.
| notification_id required | string <uuid> The unique identifier for the notification |
| type required | string Value: "v1:card:created" |
| created_at required | string <date-time> The creation timestamp of the notification in ISO 8601 format |
required | object (CardCreatedEventNotificationPayload) Base schema for card lifecycle notifications. Contains no card data beyond the references - never the card number or the redacted card number. |
{- "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
- "type": "v1:card:created",
- "created_at": "2019-08-24T14:15:22Z",
- "data": {
- "static_token_id": "3fb159c5-3595-473f-a882-31eae6265673",
- "card_id": "66f6e46c-f6a1-4af8-a1bd-49666bc01304",
- "fpan_token_id": "string",
- "card_program_id": "acba91e4-3ccc-44c0-89f3-673de52e33aa",
- "event_date": "2019-08-24T14:15:22Z",
- "form_factor": "virtual",
- "status": "string"
}
}This notification is sent when a card has been activated and can be used.
| notification_id required | string <uuid> The unique identifier for the notification |
| type required | string Value: "v1:card:activated" |
| created_at required | string <date-time> The creation timestamp of the notification in ISO 8601 format |
required | object (CardActivatedEventNotificationPayload) Base schema for card lifecycle notifications. Contains no card data beyond the references - never the card number or the redacted card number. |
{- "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
- "type": "v1:card:activated",
- "created_at": "2019-08-24T14:15:22Z",
- "data": {
- "static_token_id": "3fb159c5-3595-473f-a882-31eae6265673",
- "card_id": "66f6e46c-f6a1-4af8-a1bd-49666bc01304",
- "fpan_token_id": "string",
- "card_program_id": "acba91e4-3ccc-44c0-89f3-673de52e33aa",
- "event_date": "2019-08-24T14:15:22Z",
- "form_factor": "virtual",
- "activated_at": "2019-08-24T14:15:22Z",
- "replaces_fpan_token_id": "string"
}
}This notification is sent when a card's expiry date has changed, for example after a renewal.
| notification_id required | string <uuid> The unique identifier for the notification |
| type required | string Value: "v1:card:updated" |
| created_at required | string <date-time> The creation timestamp of the notification in ISO 8601 format |
required | object (CardUpdatedEventNotificationPayload) Base schema for card lifecycle notifications. Contains no card data beyond the references - never the card number or the redacted card number. |
{- "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
- "type": "v1:card:updated",
- "created_at": "2019-08-24T14:15:22Z",
- "data": {
- "static_token_id": "3fb159c5-3595-473f-a882-31eae6265673",
- "card_id": "66f6e46c-f6a1-4af8-a1bd-49666bc01304",
- "fpan_token_id": "string",
- "card_program_id": "acba91e4-3ccc-44c0-89f3-673de52e33aa",
- "event_date": "2019-08-24T14:15:22Z",
- "form_factor": "virtual",
- "expiry_month": "st",
- "expiry_year": "st"
}
}This notification is sent when a card has been locked.
| notification_id required | string <uuid> The unique identifier for the notification |
| type required | string Value: "v1:card:locked" |
| created_at required | string <date-time> The creation timestamp of the notification in ISO 8601 format |
required | object (CardLockedEventNotificationPayload) Base schema for card lifecycle notifications. Contains no card data beyond the references - never the card number or the redacted card number. |
{- "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
- "type": "v1:card:locked",
- "created_at": "2019-08-24T14:15:22Z",
- "data": {
- "static_token_id": "3fb159c5-3595-473f-a882-31eae6265673",
- "card_id": "66f6e46c-f6a1-4af8-a1bd-49666bc01304",
- "fpan_token_id": "string",
- "card_program_id": "acba91e4-3ccc-44c0-89f3-673de52e33aa",
- "event_date": "2019-08-24T14:15:22Z",
- "form_factor": "virtual",
- "status_reason_code": "string"
}
}This notification is sent when a card has been unlocked.
| notification_id required | string <uuid> The unique identifier for the notification |
| type required | string Value: "v1:card:unlocked" |
| created_at required | string <date-time> The creation timestamp of the notification in ISO 8601 format |
required | object (CardUnlockedEventNotificationPayload) Base schema for card lifecycle notifications. Contains no card data beyond the references - never the card number or the redacted card number. |
{- "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
- "type": "v1:card:unlocked",
- "created_at": "2019-08-24T14:15:22Z",
- "data": {
- "static_token_id": "3fb159c5-3595-473f-a882-31eae6265673",
- "card_id": "66f6e46c-f6a1-4af8-a1bd-49666bc01304",
- "fpan_token_id": "string",
- "card_program_id": "acba91e4-3ccc-44c0-89f3-673de52e33aa",
- "event_date": "2019-08-24T14:15:22Z",
- "form_factor": "virtual",
- "status_reason_code": "string"
}
}This notification is sent when a card has been permanently deactivated.
| notification_id required | string <uuid> The unique identifier for the notification |
| type required | string Value: "v1:card:deactivated" |
| created_at required | string <date-time> The creation timestamp of the notification in ISO 8601 format |
required | object (CardDeactivatedEventNotificationPayload) Base schema for card lifecycle notifications. Contains no card data beyond the references - never the card number or the redacted card number. |
{- "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
- "type": "v1:card:deactivated",
- "created_at": "2019-08-24T14:15:22Z",
- "data": {
- "static_token_id": "3fb159c5-3595-473f-a882-31eae6265673",
- "card_id": "66f6e46c-f6a1-4af8-a1bd-49666bc01304",
- "fpan_token_id": "string",
- "card_program_id": "acba91e4-3ccc-44c0-89f3-673de52e33aa",
- "event_date": "2019-08-24T14:15:22Z",
- "form_factor": "virtual",
- "status_reason_code": "string",
- "replacement_reason_code": "string"
}
}Notifications sent to your backend when a card PIN is locked or unlocked, for example so you can inform your customer.
This notification is sent when a card PIN is locked - either automatically after the PIN-try limit is exceeded, or manually.
| notification_id required | string <uuid> The unique identifier for the notification |
| type required | string Value: "v1:card:pin:locked" |
| created_at required | string <date-time> The creation timestamp of the notification in ISO 8601 format |
required | object (CardPinLockedEventNotificationPayload) Base schema for card PIN lock status change notifications. |
{- "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
- "type": "v1:card:pin:locked",
- "created_at": "2019-08-24T14:15:22Z",
- "data": {
- "static_token_id": "3fb159c5-3595-473f-a882-31eae6265673",
- "fpan_token_id": "string",
- "card_program_id": "acba91e4-3ccc-44c0-89f3-673de52e33aa",
- "lock_reason": "string",
- "lock_date": "2019-08-24T14:15:22Z"
}
}This notification is sent when a card PIN is unlocked.
| notification_id required | string <uuid> The unique identifier for the notification |
| type required | string Value: "v1:card:pin:unlocked" |
| created_at required | string <date-time> The creation timestamp of the notification in ISO 8601 format |
required | object (CardPinUnlockedEventNotificationPayload) Base schema for card PIN lock status change notifications. |
{- "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
- "type": "v1:card:pin:unlocked",
- "created_at": "2019-08-24T14:15:22Z",
- "data": {
- "static_token_id": "3fb159c5-3595-473f-a882-31eae6265673",
- "fpan_token_id": "string",
- "card_program_id": "acba91e4-3ccc-44c0-89f3-673de52e33aa",
- "unlock_reason": "string",
- "unlock_date": "2019-08-24T14:15:22Z"
}
}APIs related to authorization messages. These are messages sent from our platform to your backend.
See Authorization message for more details.
Notification sent as soon as a push to card (a credit pushed to the card, e.g. Mastercard Send) is approved on your behalf, so you can show the incoming funds to the customer before the clearing file arrives. Sent only for transaction_category = push_to_card.
| notification_id required | string <uuid> The unique identifier for the notification |
| type required | string Value: "v1:pba:transaction:push_to_card_received" |
| created_at required | string <date-time> The creation timestamp of the notification in ISO 8601 format |
required | object (PbaPushToCardReceivedNotification) 'v1:pba:transaction:push_to_card_received'. Sent as soon as a push to card (a credit pushed to the card, e.g.
Mastercard Send) is approved, so the funds can be shown to the customer before the clearing file arrives.
Published only for |
{- "notification_id": "b16a7072-3deb-46d3-aad0-5b95da03e8e4",
- "type": "v1:pba:transaction:push_to_card_received",
- "created_at": "2026-03-21T00:23:27Z",
- "data": {
- "notification_id": "b16a7072-3deb-46d3-aad0-5b95da03e8e4",
- "transaction_id": "830cde24-7c70-461b-a3e4-1d6ad2aa34dc",
- "network_transaction_ref": "MCC8855210320",
- "network_message_ref": "906990",
- "transaction_category": "push_to_card",
- "network_message_timestamp": "2026-03-21T00:23:20Z",
- "transaction_type": "refund_online",
- "transaction_status": "processed",
- "transaction_source": "ecommerce",
- "customer_id": "2c9c0f5e-1f6a-4a3f-9c3d-5b1f8e9a7d21",
- "authorization_code": "123456",
- "amount": 20,
- "currency": "USD",
- "billing_amount": 20,
- "billing_currency_code": "USD",
- "billing_exchange_rate": 1,
- "settlement_amount": 20,
- "settlement_currency_code": "USD",
- "settlement_exchange_rate": 1,
- "network_merchant_country_code": "US"
}
}Ledger operations that Open Fabric calls on your backend to apply balance changes (debit/credit/hold/release).
See Ledger APIs for more details.
Debits a customer's balance.
| account_id required | string Open Fabric's account ID. |
| tenant_account_ref | string Your reference for the account. |
| customer_id | string Open Fabric's customer ID. |
| tenant_customer_ref | string Your reference for the customer. |
| amount | number Amount to apply, in major units of |
| currency | string = 3 characters ^[A-Z]{3}$ ISO 4217 code of |
| billing_amount | number The same money as |
| billing_currency | string = 3 characters ^[A-Z]{3}$ ISO 4217 code of |
| network_transaction_ref required | string Open Fabric's transaction ID. |
| network_lifecycle_ref | string The hold reference you returned on |
| network_message_timestamp | string Timestamp of the card network message (ISO 8601). |
object |
{- "account_id": "string",
- "tenant_account_ref": "string",
- "customer_id": "string",
- "tenant_customer_ref": "string",
- "amount": 25,
- "currency": "EUR",
- "billing_amount": 30.04,
- "billing_currency": "USD",
- "network_transaction_ref": "string",
- "network_lifecycle_ref": "string",
- "network_message_timestamp": "string",
- "metadata": {
- "idempotency_key": "string",
- "of_action_ref": "string"
}
}{- "status": "success",
- "transaction_ref": "string",
- "network_lifecycle_ref": "string",
- "available_balance": 0,
- "hold_balance": 0,
- "currency": "str",
- "error_code": "string",
- "message": "string"
}Credits a customer's balance, for a refund or an adjustment.
| account_id required | string Open Fabric's account ID. |
| tenant_account_ref | string Your reference for the account. |
| customer_id | string Open Fabric's customer ID. |
| tenant_customer_ref | string Your reference for the customer. |
| amount | number Amount to apply, in major units of |
| currency | string = 3 characters ^[A-Z]{3}$ ISO 4217 code of |
| billing_amount | number The same money as |
| billing_currency | string = 3 characters ^[A-Z]{3}$ ISO 4217 code of |
| network_transaction_ref required | string Open Fabric's transaction ID. |
| network_lifecycle_ref | string The hold reference you returned on |
| network_message_timestamp | string Timestamp of the card network message (ISO 8601). |
object |
{- "account_id": "string",
- "tenant_account_ref": "string",
- "customer_id": "string",
- "tenant_customer_ref": "string",
- "amount": 25,
- "currency": "EUR",
- "billing_amount": 30.04,
- "billing_currency": "USD",
- "network_transaction_ref": "string",
- "network_lifecycle_ref": "string",
- "network_message_timestamp": "string",
- "metadata": {
- "idempotency_key": "string",
- "of_action_ref": "string"
}
}{- "status": "success",
- "transaction_ref": "string",
- "network_lifecycle_ref": "string",
- "available_balance": 0,
- "hold_balance": 0,
- "currency": "str",
- "error_code": "string",
- "message": "string"
}Places a hold on funds for a pre-authorization, or raises an existing hold (named by network_lifecycle_ref) by amount. Return your hold reference as network_lifecycle_ref.
| account_id required | string Open Fabric's account ID. |
| tenant_account_ref | string Your reference for the account. |
| customer_id | string Open Fabric's customer ID. |
| tenant_customer_ref | string Your reference for the customer. |
| amount | number Amount to apply, in major units of |
| currency | string = 3 characters ^[A-Z]{3}$ ISO 4217 code of |
| billing_amount | number The same money as |
| billing_currency | string = 3 characters ^[A-Z]{3}$ ISO 4217 code of |
| network_transaction_ref required | string Open Fabric's transaction ID. |
| network_lifecycle_ref | string The hold reference you returned on |
| network_message_timestamp | string Timestamp of the card network message (ISO 8601). |
object |
{- "account_id": "string",
- "tenant_account_ref": "string",
- "customer_id": "string",
- "tenant_customer_ref": "string",
- "amount": 25,
- "currency": "EUR",
- "billing_amount": 30.04,
- "billing_currency": "USD",
- "network_transaction_ref": "string",
- "network_lifecycle_ref": "string",
- "network_message_timestamp": "string",
- "metadata": {
- "idempotency_key": "string",
- "of_action_ref": "string"
}
}{- "status": "success",
- "transaction_ref": "string",
- "network_lifecycle_ref": "string",
- "available_balance": 0,
- "hold_balance": 0,
- "currency": "str",
- "error_code": "string",
- "message": "string"
}Releases amount of a hold back to the available balance.
| account_id required | string Open Fabric's account ID. |
| tenant_account_ref | string Your reference for the account. |
| customer_id | string Open Fabric's customer ID. |
| tenant_customer_ref | string Your reference for the customer. |
| amount | number Amount to apply, in major units of |
| currency | string = 3 characters ^[A-Z]{3}$ ISO 4217 code of |
| billing_amount | number The same money as |
| billing_currency | string = 3 characters ^[A-Z]{3}$ ISO 4217 code of |
| network_transaction_ref required | string Open Fabric's transaction ID. |
| network_lifecycle_ref | string The hold reference you returned on |
| network_message_timestamp | string Timestamp of the card network message (ISO 8601). |
object |
{- "account_id": "string",
- "tenant_account_ref": "string",
- "customer_id": "string",
- "tenant_customer_ref": "string",
- "amount": 25,
- "currency": "EUR",
- "billing_amount": 30.04,
- "billing_currency": "USD",
- "network_transaction_ref": "string",
- "network_lifecycle_ref": "string",
- "network_message_timestamp": "string",
- "metadata": {
- "idempotency_key": "string",
- "of_action_ref": "string"
}
}{- "status": "success",
- "transaction_ref": "string",
- "network_lifecycle_ref": "string",
- "available_balance": 0,
- "hold_balance": 0,
- "currency": "str",
- "error_code": "string",
- "message": "string"
}Debits amount from a hold. Without network_lifecycle_ref (an offline pre-authorization with no hold), debit the balance instead.
| account_id required | string Open Fabric's account ID. |
| tenant_account_ref | string Your reference for the account. |
| customer_id | string Open Fabric's customer ID. |
| tenant_customer_ref | string Your reference for the customer. |
| amount | number Amount to apply, in major units of |
| currency | string = 3 characters ^[A-Z]{3}$ ISO 4217 code of |
| billing_amount | number The same money as |
| billing_currency | string = 3 characters ^[A-Z]{3}$ ISO 4217 code of |
| network_transaction_ref required | string Open Fabric's transaction ID. |
| network_lifecycle_ref | string The hold reference you returned on |
| network_message_timestamp | string Timestamp of the card network message (ISO 8601). |
object |
{- "account_id": "string",
- "tenant_account_ref": "string",
- "customer_id": "string",
- "tenant_customer_ref": "string",
- "amount": 25,
- "currency": "EUR",
- "billing_amount": 30.04,
- "billing_currency": "USD",
- "network_transaction_ref": "string",
- "network_lifecycle_ref": "string",
- "network_message_timestamp": "string",
- "metadata": {
- "idempotency_key": "string",
- "of_action_ref": "string"
}
}{- "status": "success",
- "transaction_ref": "string",
- "network_lifecycle_ref": "string",
- "available_balance": 0,
- "hold_balance": 0,
- "currency": "str",
- "error_code": "string",
- "message": "string"
}Adds amount back to a hold.
| account_id required | string Open Fabric's account ID. |
| tenant_account_ref | string Your reference for the account. |
| customer_id | string Open Fabric's customer ID. |
| tenant_customer_ref | string Your reference for the customer. |
| amount | number Amount to apply, in major units of |
| currency | string = 3 characters ^[A-Z]{3}$ ISO 4217 code of |
| billing_amount | number The same money as |
| billing_currency | string = 3 characters ^[A-Z]{3}$ ISO 4217 code of |
| network_transaction_ref required | string Open Fabric's transaction ID. |
| network_lifecycle_ref | string The hold reference you returned on |
| network_message_timestamp | string Timestamp of the card network message (ISO 8601). |
object |
{- "account_id": "string",
- "tenant_account_ref": "string",
- "customer_id": "string",
- "tenant_customer_ref": "string",
- "amount": 25,
- "currency": "EUR",
- "billing_amount": 30.04,
- "billing_currency": "USD",
- "network_transaction_ref": "string",
- "network_lifecycle_ref": "string",
- "network_message_timestamp": "string",
- "metadata": {
- "idempotency_key": "string",
- "of_action_ref": "string"
}
}{- "status": "success",
- "transaction_ref": "string",
- "network_lifecycle_ref": "string",
- "available_balance": 0,
- "hold_balance": 0,
- "currency": "str",
- "error_code": "string",
- "message": "string"
}Notifications related to reversals. These are messages sent from our platform to your backend.
See Reversal notifications for more details.
Notification sent when a previously approved final authorization is reversed.
See Reversal notifications for more details.
| notification_id required | string <uuid> The unique identifier for the notification |
| type required | string Value: "v1:pba:transaction:final_auth_reversed" |
| created_at required | string <date-time> The creation timestamp of the notification in ISO 8601 format |
required | object (FinalAuthReversalNotification) v1:pba:transaction:final_auth_reversed |
{- "notification_id": "b16a7072-3deb-46d3-aad0-5b95da03e8e4",
- "type": "v1:pba:transaction:final_auth_reversed",
- "created_at": "2026-03-21T00:23:27Z",
- "data": {
- "notification_id": "b16a7072-3deb-46d3-aad0-5b95da03e8e4",
- "transaction_id": "830cde24-7c70-461b-a3e4-1d6ad2aa34dc",
- "tenant_reference_id": "99c0b3cd-ea78-45f0-8b76-8aa2e91f12ab",
- "network_transaction_ref": "MCC8855210320",
- "network_message_ref": "906990",
- "amount": 20,
- "currency": "USD",
- "billing_amount": 20,
- "billing_currency_code": "USD",
- "billing_exchange_rate": 1,
- "settlement_amount": 20,
- "settlement_currency_code": "USD",
- "settlement_exchange_rate": 1,
- "network_merchant_country_code": "US"
}
}Notification sent when a previously approved pre-authorization is reversed.
See Reversal notifications for more details.
| notification_id required | string <uuid> The unique identifier for the notification |
| type required | string Value: "v1:pba:transaction:pre_auth_reversed" |
| created_at required | string <date-time> The creation timestamp of the notification in ISO 8601 format |
required | object (PreAuthReversalNotification) v1:pba:transaction:pre_auth_reversed |
{- "notification_id": "b16a7072-3deb-46d3-aad0-5b95da03e8e4",
- "type": "v1:pba:transaction:pre_auth_reversed",
- "created_at": "2026-03-21T00:23:27Z",
- "data": {
- "notification_id": "b16a7072-3deb-46d3-aad0-5b95da03e8e4",
- "transaction_id": "830cde24-7c70-461b-a3e4-1d6ad2aa34dc",
- "tenant_reference_id": "99c0b3cd-ea78-45f0-8b76-8aa2e91f12ab",
- "network_transaction_ref": "MCC8855210320",
- "network_message_ref": "906990",
- "amount": 20,
- "currency": "USD",
- "billing_amount": 20,
- "billing_currency_code": "USD",
- "billing_exchange_rate": 1,
- "settlement_amount": 20,
- "settlement_currency_code": "USD",
- "settlement_exchange_rate": 1,
- "network_merchant_country_code": "US"
}
}Notification sent when a previously received push to card is reversed by the acquirer, or declined by the network in stand-in before our approval arrived. The credit reported by the push to card received notification is no longer due.
| notification_id required | string <uuid> The unique identifier for the notification |
| type required | string Value: "v1:pba:transaction:push_to_card_reversed" |
| created_at required | string <date-time> The creation timestamp of the notification in ISO 8601 format |
required | object (PbaPushToCardReversedNotification) 'v1:pba:transaction:push_to_card_reversed'. Sent when an approved push to card is reversed: the acquirer reversed
it (0400 / 0420), or the network declined it in stand-in before our approval arrived (decline advice). The credit
reported by |
{- "notification_id": "b16a7072-3deb-46d3-aad0-5b95da03e8e4",
- "type": "v1:pba:transaction:push_to_card_reversed",
- "created_at": "2026-03-21T00:23:27Z",
- "data": {
- "notification_id": "b16a7072-3deb-46d3-aad0-5b95da03e8e4",
- "transaction_id": "830cde24-7c70-461b-a3e4-1d6ad2aa34dc",
- "network_transaction_ref": "MCC8855210320",
- "network_message_ref": "906990",
- "transaction_category": "push_to_card",
- "transaction_status": "reversed",
- "reason": "Reversed by the acquirer",
- "amount": 20,
- "currency": "USD",
- "billing_amount": 20,
- "billing_currency_code": "USD",
- "billing_exchange_rate": 1,
- "settlement_amount": 20,
- "settlement_currency_code": "USD",
- "settlement_exchange_rate": 1,
- "network_merchant_country_code": "US"
}
}APIs and messages used to complete 3D Secure challenges during payment processing.
See Handle 3D Secure Payments for more details.
This notification is sent to your backend when a 3D Secure challenge requires an out-of-band (OOB) challenge to be completed.
See 3DS Out of Band (OOB) challenge flow for more details.
| three_ds_challenge_id required | string 3DS Request ID in Open Fabric |
| tenant_customer_ref required | string Customer identifier in your system |
| customer_id required | string Customer identifier in Open Fabric |
| tenant_account_ref required | string Account identifier in your system |
| account_id required | string Account identifier in Open Fabric |
| static_token_id | string Static token identifier in Open Fabric representing a Virtual Card |
| digital_token_id | string Digital token identifier in Open Fabric representing a Digital Wallet Token |
| merchant_name required | string Name of the merchant |
| transaction_amount | number Amount of the transaction. If not present or 0, it is a non-payment 3DS authentication. |
| transaction_currency | string Currency code for the transaction (e.g., USD, EUR). Not present for non-payment 3DS authentications. |
| creation_time required | string <date-time> Creation time of the 3DS request in ISO 8601 format |
{- "three_ds_challenge_id": "string",
- "tenant_customer_ref": "string",
- "customer_id": "string",
- "tenant_account_ref": "string",
- "account_id": "string",
- "static_token_id": "string",
- "digital_token_id": "string",
- "merchant_name": "string",
- "transaction_amount": 0,
- "transaction_currency": "string",
- "creation_time": "2019-08-24T14:15:22Z"
}This API is used for you to update our system with the 3DS challenge response in case of the Out of Band (OOB) challenge flow.
See 3DS Out of Band (OOB) challenge flow for more details.
| three_ds_challenge_id required | string 3DS Request ID in Open Fabric |
| static_token_id | string Static token identifier in Open Fabric representing a Virtual Card. Provided for
static-token 3DS flows (e.g. ACS). For digitization flows provide
|
| digital_token_id | string Digital token id, provided for digitization 3DS/OTP flows where a static token id is not available. |
| tenant_customer_ref required | string Customer identifier in your system |
| tenant_account_ref required | string Account identifier in your system |
| challenge_result required | string (TenantThreeDsActionResult) Enum: "approved" "declined" Result of the 3DS challenge |
| reason | string Required if |
| creation_time required | string <date-time> Creation time of the 3DS response in ISO 8601 format |
{- "three_ds_challenge_id": "string",
- "static_token_id": "string",
- "digital_token_id": "string",
- "tenant_customer_ref": "string",
- "tenant_account_ref": "string",
- "challenge_result": "approved",
- "reason": "string",
- "creation_time": "2019-08-24T14:15:22Z"
}{- "error_code": "string",
- "message": "string",
- "details": [
- {
- "error_code": "string",
- "message": "string",
- "param": "string",
- "reason_code": "string",
- "reason": "string"
}
]
}This notification is sent to your backend when a 3D Secure challenge requires an OTP to be sent to the cardholder.
See 3DS OTP flow for more details.
| three_ds_challenge_id required | string 3DS Request ID in Open Fabric |
| tenant_customer_ref required | string Customer identifier in your system |
| customer_id required | string Customer identifier in Open Fabric |
| tenant_account_ref required | string Account identifier in your system |
| account_id required | string Account identifier in Open Fabric |
| static_token_id | string Static token identifier in Open Fabric representing a Virtual Card |
| digital_token_id | string Digital token identifier in Open Fabric representing a Digital Wallet Token |
| merchant_name required | string Name of the merchant |
| transaction_amount | number Amount of the transaction. If not present or 0, it is a non-payment 3DS authentication. |
| transaction_currency | string Currency code for the transaction (e.g., USD, EUR). Not present for non-payment 3DS authentications. |
| creation_time required | string <date-time> Creation time of the 3DS request in ISO 8601 format |
| authentication_credential | string The OTP sent to the customer |
| encrypted_authentication_credential | string A JWE-encrypted string containing the OTP sent to the customer. When pre-configured between yourself and Open Fabric, the OTP is delivered in encrypted form using an encryption key exchanged offline during onboarding. |
| delivery_channels | Array of strings (Pba3dsChallengeDeliveryChannel) Items Enum: "sms" "email" "voice" Delivery channels to use for the 3DS OTP notification |
object (PbaDeviceInfo) |
{- "three_ds_challenge_id": "string",
- "tenant_customer_ref": "string",
- "customer_id": "string",
- "tenant_account_ref": "string",
- "account_id": "string",
- "static_token_id": "string",
- "digital_token_id": "string",
- "merchant_name": "string",
- "transaction_amount": 0,
- "transaction_currency": "string",
- "creation_time": "2019-08-24T14:15:22Z",
- "authentication_credential": "string",
- "encrypted_authentication_credential": "string",
- "delivery_channels": [
- "sms"
], - "device_info": {
- "device_fingerprint": "string",
- "device_name": "string",
- "serial_number": "string",
- "device_type": "string",
- "os_name": "string",
- "os_version": "string",
- "imei": "string",
- "msisdn": "string",
- "nfc_capable": true
}
}{- "three_ds_challenge_id": "string",
- "masked_email": "string",
- "masked_phone_number": "string"
}Notifications sent from our platform to your backend when a clearing or settlement report is ready, plus the API to generate a fresh download URL once the one in the notification expires.
See Clearing reports and Settlement for more details.
| network_clearing_ref required | string A unique identifier for this clearing instruction received from the network |
| type required | string (PbaClearingType) Enum: "final_auth" "final_auth_reversal" "final_auth_partial" "final_auth_partial_reversal" "pre_auth_partial" "pre_auth_partial_reversal" "pre_auth_final" "pre_auth_final_reversal" "final_auth_expiry" "pre_auth_expiry" "refund" "refund_reversal" "refund_expiry" "chargeback_challenge" "chargeback_challenge_reversal" "chargeback" "chargeback_reversal" "fee_collection_credit" "fee_collection_credit_reversal" "fee_collection_debit" "fee_collection_debit_reversal" "unlinked_auth_partial" "unlinked_auth_final" "unlinked_auth_partial_reversal" "unlinked_auth_final_reversal" "unlinked_refund" "unlinked_refund_reversal" "unlinked_chargeback" The type of clearing instruction |
| transfer_type required | string (PbaTransferType) Enum: "consumer_debit" "consumer_credit" "ahi_debit" "ahi_credit" The direction of transfer deferred from
Examples:
|
| is_potential_chargeback required | boolean Indicator received from the network signaling that this clearing instruction may result in a chargeback (e.g. total clearing amount exceeds the original authorized amount). You should follow the instruction to clear the amount and may decide to initiate a chargeback for the additional amount at your discretion. |
| original_transaction_id | string The transaction identifier of the original authorization in Open Fabric. Not present for all unlinked types and fee_collection. For Refund and Chargeback, this refers to the original final authorization or pre-authorization transaction that this refund is linked to. |
| transaction_id | string Transaction identifier of this clearing instruction itself. Only populated when using the Ledger APIs. |
| network_transaction_ref | string Transaction Reference received from the network |
| network_acquirer_transaction_ref | string Acquirer Transaction Reference received from the network |
| original_tenant_transaction_ref | string The original transaction identifier of the original authorization in your system. Not present for all unlinked types and fee_collection. For Refund and Chargeback, this refers to the original final authorization or pre-authorization transaction that this refund is linked to. |
| customer_id | string Customer identifier in Open Fabric |
| tenant_customer_ref | string Customer reference identifier in tenant system |
| account_id | string <uuid> Tokenized account identifier in Open Fabric |
| tenant_account_ref | string Account identifier in your system |
| provision_id | string <uuid> Provision identifier in Open Fabric |
| provision_type | string (PbaOutboundProvisionType) Enum: "customer_account_device" "static_token" "google_pay" "samsung_pay" "apple_pay" "unknown" Provision type in Open Fabric.
|
| network_message_origin_ref | string Original network message reference of the linked authorization |
| network_merchant_name required | string Merchant name received from the network |
| network_merchant_outlet_address required | string Merchant outlet address received from the network |
| network_merchant_id required | string Merchant ID received from the network |
| amount required | number Transaction amount in major units |
| currency required | string Transaction currency code (ISO 4217) |
| billing_amount required | number Billing amount in major units |
| billing_currency_code required | string Billing currency code (ISO 4217) |
| billing_exchange_rate required | number Exchange rate when calculating billing amount |
| settlement_amount required | number Settlement amount in major units |
| settlement_currency_code required | string Settlement currency code (ISO 4217) |
| settlement_exchange_rate required | number Exchange rate when calculating settlement amount |
| interchange_fee_amount required | number Interchange fee amount in major units |
| interchange_fee_currency_code required | string Interchange fee currency code (ISO 4217) |
| network_clearing_file_ref required | string Reference ID for the clearing file (EOC report) received from the network |
| network_clearing_file_name required | string Name of the clearing file (EOC report) received from the network |
| network_clearing_timestamp required | string Timestamp of the clearing file (EOC report) received from the network |
| transaction_source required | string (PbaTransactionSource) Enum: "ecommerce" "terminal" "unsupported_dfle" "unsupported_tagc" "unsupported_brcd" "unsupported_mgst" "unsupported_unkw" "unsupported_mail" "unsupported_tlph" "unsupported_tvpy" "unsupported_mobl" The source of the transaction:
|
| transaction_category | string (PbaTransactionCategory) Enum: "high_risk_purchase" "recurring_payment" "transit" "automated_fuel_dispenser" "dynamic_currency_conversion" "cardholder_activated_terminal" "card_validity_check" "cash_withdrawal" "push_to_card" "other" The category of the transaction determined by Open Fabric |
| network_posting_file_id required | string The network identifier of the file used for posting to the cardholder’s account in which the transaction appeared. For Mastercard, it is the identifier of the GCMS file. |
| network_merchant_category_code | string Merchant category code received from the network |
| network_acquirer_id required | string Merchant acquirer ID received from the network |
| network_merchant_country_code | string Country Code - ISO 3166 Alpha-2 |
| is_converted_pre_auth required | boolean True indicates this is a final authorization converted from a pre-authorization |
| network_merchant_terminal_id | string Merchant terminal ID received from the network |
| network_merchant_city | string Merchant city received from the network |
| card_program_id | string ID of the card program in which the transaction occurred |
| financial_account_id | string Card program prefix + tenant account reference used in the transaction |
{- "network_clearing_ref": "string",
- "type": "final_auth",
- "transfer_type": "consumer_debit",
- "is_potential_chargeback": true,
- "original_transaction_id": "string",
- "transaction_id": "string",
- "network_transaction_ref": "string",
- "network_acquirer_transaction_ref": "string",
- "original_tenant_transaction_ref": "string",
- "customer_id": "string",
- "tenant_customer_ref": "string",
- "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
- "tenant_account_ref": "string",
- "provision_id": "3411849f-c321-45a4-8ab1-3bbb49f5b43b",
- "provision_type": "customer_account_device",
- "network_message_origin_ref": "string",
- "network_merchant_name": "string",
- "network_merchant_outlet_address": "string",
- "network_merchant_id": "string",
- "amount": 0,
- "currency": "string",
- "billing_amount": 0,
- "billing_currency_code": "string",
- "billing_exchange_rate": 0,
- "settlement_amount": 0,
- "settlement_currency_code": "string",
- "settlement_exchange_rate": 0,
- "interchange_fee_amount": 0,
- "interchange_fee_currency_code": "string",
- "network_clearing_file_ref": "string",
- "network_clearing_file_name": "string",
- "network_clearing_timestamp": "string",
- "transaction_source": "ecommerce",
- "transaction_category": "high_risk_purchase",
- "network_posting_file_id": "string",
- "network_merchant_category_code": "string",
- "network_acquirer_id": "string",
- "network_merchant_country_code": "string",
- "is_converted_pre_auth": true,
- "network_merchant_terminal_id": "string",
- "network_merchant_city": "string",
- "card_program_id": "string",
- "financial_account_id": "string"
}required | object (ReconciliationAndNetSettlementSummary) |
required | Array of objects (SettlementRecordDetail) |
{- "reconciliationAndNetSettlementSummary": {
- "network_settlement_file_ref": "string",
- "network_settlement_file_name": "string",
- "network_reconciliation_date": "string",
- "network_reconciliation_timestamp": "string",
- "interbank_settlement_date": "string",
- "transfer_currency_code": "string",
- "transfer_amount": 0,
- "transfer_type": "consumer_debit",
- "transfer_payment_message_ref": "string",
- "transfer_end_to_end_ref": "string",
- "transfer_requested_exec_date": "string",
- "settlement_currency_code": "string",
- "total_net_recon_amount": 0,
- "total_credit_txn_amount": 0,
- "total_credit_number_of_txn": 0,
- "total_credit_chargeback_amount": 0,
- "total_credit_number_of_chargeback": 0,
- "total_credit_reversal_amount": 0,
- "total_credit_number_of_reversal": 0,
- "total_credit_interchange_fee_amount": 0,
- "total_debit_txn_amount": 0,
- "total_debit_number_of_txn": 0,
- "total_debit_chargeback_amount": 0,
- "total_debit_number_of_chargeback": 0,
- "total_debit_reversal_amount": 0,
- "total_debit_number_of_reversal": 0,
- "total_debit_interchange_fee_amount": 0,
- "total_number_of_auth": 0,
- "total_number_of_auth_reversal": 0,
- "network_settlement_timestamp": "string",
- "card_program_id": "acba91e4-3ccc-44c0-89f3-673de52e33aa",
- "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
- "tenant_name": "string"
}, - "settlementRecordDetails": [
- {
- "network_settlement_ref": "string",
- "type": "final_auth",
- "transfer_type": "consumer_debit",
- "is_potential_chargeback": true,
- "network_settlement_file_ref": "string",
- "network_settlement_file_name": "string",
- "original_transaction_id": "string",
- "transaction_id": "string",
- "network_transaction_ref": "string",
- "network_acquirer_transaction_ref": "string",
- "original_tenant_transaction_ref": "string",
- "customer_id": "string",
- "tenant_customer_ref": "string",
- "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
- "tenant_account_ref": "string",
- "provision_id": "3411849f-c321-45a4-8ab1-3bbb49f5b43b",
- "provision_type": "customer_account_device",
- "network_message_origin_ref": "string",
- "network_merchant_name": "string",
- "network_merchant_outlet_address": "string",
- "network_merchant_id": "string",
- "amount": 0,
- "currency": "string",
- "billing_amount": 0,
- "billing_currency_code": "string",
- "billing_exchange_rate": 0,
- "settlement_amount": 0,
- "settlement_currency_code": "string",
- "settlement_exchange_rate": 0,
- "interchange_fee_amount": 0,
- "interchange_fee_currency_code": "string",
- "network_settlement_timestamp": "string",
- "transaction_source": "ecommerce",
- "transaction_category": "high_risk_purchase",
- "network_posting_file_id": "string",
- "network_merchant_category_code": "string",
- "network_acquirer_id": "string",
- "network_merchant_country_code": "string",
- "is_converted_pre_auth": true,
- "network_merchant_terminal_id": "string",
- "network_merchant_city": "string",
- "card_program_id": "string",
- "financial_account_id": "string"
}
]
}Notification sent when a clearing file is ready to be processed.
| notification_id required | string <uuid> The unique identifier for the notification |
| type required | string Value: "v1:pba:eoc:clearing_file_ready" |
| created_at required | string <date-time> The creation timestamp of the notification in ISO 8601 format |
required | object (EOCFileProcessedNotification) v1:pba:eoc:clearing_file_ready |
{- "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
- "type": "v1:pba:eoc:clearing_file_ready",
- "created_at": "2019-08-24T14:15:22Z",
- "data": {
- "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
- "card_program_id": "acba91e4-3ccc-44c0-89f3-673de52e33aa",
- "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
- "tenant_name": "string",
- "file_name": "string",
- "file_ref": "string",
- "file_checksum": "string",
- "network_file_id": "string",
- "network_timestamp": "2019-08-24T14:15:22Z",
- "number_of_instructions": 0,
- "download_url": "string",
- "download_url_expires_at": "2019-08-24T14:15:22Z"
}
}Notification sent when a settlement file is ready to be processed.
| notification_id required | string <uuid> The unique identifier for the notification |
| type required | string Value: "v1:pba:eos:net_settlement_file_ready" |
| created_at required | string <date-time> The creation timestamp of the notification in ISO 8601 format |
required | object (EOSNetSettlementNotification) v1:pba:eos:net_settlement_file_ready |
{- "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
- "type": "v1:pba:eos:net_settlement_file_ready",
- "created_at": "2019-08-24T14:15:22Z",
- "data": {
- "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
- "card_program_id": "acba91e4-3ccc-44c0-89f3-673de52e33aa",
- "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
- "tenant_name": "string",
- "file_name": "string",
- "file_ref": "string",
- "file_checksum": "string",
- "network_file_id": "string",
- "network_timestamp": "2019-08-24T14:15:22Z",
- "reconciliation_date": "string",
- "interbank_settlement_date": "string",
- "settlement_currency_code": "string",
- "total_net_recon_amount": 0,
- "total_credit_txn_amount": 0,
- "total_credit_number_of_txn": 0,
- "total_credit_chargeback_amount": 0,
- "total_credit_number_of_chargeback": 0,
- "total_credit_reversal_amount": 0,
- "total_credit_number_of_reversal": 0,
- "total_credit_interchange_fee_amount": 0,
- "total_debit_txn_amount": 0,
- "total_debit_number_of_txn": 0,
- "total_debit_chargeback_amount": 0,
- "total_debit_number_of_chargeback": 0,
- "total_debit_reversal_amount": 0,
- "total_debit_number_of_reversal": 0,
- "total_debit_interchange_fee_amount": 0,
- "total_number_of_auth": 0,
- "total_number_of_auth_reversal": 0,
- "download_url": "string",
- "download_url_expires_at": "2019-08-24T14:15:22Z"
}
}Generate a new time-limited download URL for an EOC (clearing) or EOS (settlement) report file that belongs to your tenant.
Use this API to regenerate the download_url received in the clearing file ready or settlement file ready notification after it has expired. Pass the file_ref received in the notification.
| file_ref required | string The report file reference ( |
{- "file_ref": "string"
}{- "download_url": "string",
- "expires_at": "2019-08-24T14:15:22Z"
}APIs to raise a chargeback dispute against a transaction, submit it to the card network, and follow the case. Includes the notification sent to your backend when a dispute's status changes (filed, network outcome synced, closed).
See Chargebacks for the end-to-end flow.
Creates a draft dispute against a disputable clearing record on the given transaction. Nothing is filed with the card network at this point — draft only. Fails with 404 if the transaction has no eligible clearing record.
| Idempotency-Key | string Unique value submitted by the client to ensure an idempotent request when creating a dispute. |
| original_transaction_id required | string <uuid> OpenFabric Transaction ID to raise a dispute against. |
| original_clearing_record_id | string Specific cleared record to dispute. Defaults to the sole/most-recent clearing record for the transaction. |
| reason_code required | string (DisputeReasonCode) Enum: "fraud_unauthorized_card_not_present" "goods_not_received" "defective_not_as_described" "digital_goods_not_received" "refund_not_processed" "recurring_after_cancellation" "duplicate_processing" "incorrect_amount" OpenFabric reason code, mapped internally to the corresponding chargeback reason code with the card network. |
| amount | number <double> Defaults to the full cleared amount; supply for a partial chargeback. |
| currency | string^[A-Z]{3}$ Must match the clearing record's currency (ISO 4217 Alpha-3). Defaults to it if omitted. |
| reason required | string <= 100 characters Cardholder statement, submitted to the card network as the dispute's message text. |
{- "original_transaction_id": "368700fc-be57-4411-8ef4-136caf5681c0",
- "original_clearing_record_id": "string",
- "reason_code": "fraud_unauthorized_card_not_present",
- "amount": 0.1,
- "currency": "string",
- "reason": "string"
}{- "dispute_id": "6a12a61b-d612-4dc3-8c84-e4093662a9c8",
- "status": "draft",
- "original_transaction_id": "368700fc-be57-4411-8ef4-136caf5681c0",
- "original_clearing_record_id": "string",
- "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
- "chargeback_system": "mastercom",
- "reason_code": "fraud_unauthorized_card_not_present",
- "network_reason_code": "string",
- "reason": "string",
- "amount": 0.1,
- "currency": "string",
- "authorized_amount": 0.1,
- "network_chargeback_claim_ref": "string",
- "original_clearing_transaction_id": "string",
- "is_open": true,
- "is_settlement_pending": true,
- "network_chargeback_details": {
- "amount": 0.1,
- "currency": "string",
- "network_reason_code": "string",
- "is_partial_chargeback": true,
- "message_text": "string",
- "document_indicator": true,
- "credit_posted_as_purchase": true,
- "chargeback_id": "string",
- "reject_reason": "string"
}, - "settlement": {
- "state": "none",
- "latest_clearing_type": "refund",
- "net_amount": 0.1,
- "currency": "string",
- "last_settled_at": "2019-08-24T14:15:22Z"
}, - "network_settlement": [
- {
- "clearing_type": "refund",
- "network_transaction_ref": "string",
- "amount": 0.1,
- "currency": "string",
- "direction": "credit",
- "cleared_at": "2019-08-24T14:15:22Z"
}
], - "filing_window_days": 0,
- "required_documents": [
- "fraud_attestation"
], - "recommended_documents": [
- "fraud_attestation"
], - "documents": [
- {
- "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",
- "dispute_id": "6a12a61b-d612-4dc3-8c84-e4093662a9c8",
- "evidence_type": "fraud_attestation",
- "file_name": "string",
- "content_type": "application/pdf",
- "size_bytes": 0,
- "status": "pending",
- "network_document_ref": "string",
- "is_immutable": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "checklist": {
- "satisfied": true,
- "missing_required": [
- "fraud_attestation"
]
}
}
], - "checklist": {
- "satisfied": true,
- "missing_required": [
- "fraud_attestation"
]
}, - "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}List all disputes for the tenant, filterable by transaction, status, reason code, and searchable by reference.
| original_transaction_id | string <uuid> Filter to disputes raised against this OpenFabric Transaction ID. |
| page | integer Page number, 1-indexed. Defaults to 1. |
| page_size | integer Results per page. Defaults to 20, capped at 100. |
| status | string (DisputeStatus) Enum: "draft" "submitted" "refunded" "voucher_offered" "voucher_accepted" "chargeback" "chargeback_declined" "chargeback_challenged" "chargeback_reversed" "chargeback_challenge_reversed" "pre_arbitration" "arbitration" "pre_compliance" "compliance" "closed" Filter by dispute status. |
| reason_code | string (DisputeReasonCode) Enum: "fraud_unauthorized_card_not_present" "goods_not_received" "defective_not_as_described" "digital_goods_not_received" "refund_not_processed" "recurring_after_cancellation" "duplicate_processing" "incorrect_amount" Filter by OpenFabric reason code. |
| dispute_ids | string Pipe-joined dispute (chargeback) IDs to filter to, e.g. |
| customer_id | string Filter by the disputing customer's ID. |
| currency | string^[A-Z]{3}$ Filter by currency code (ISO 4217 Alpha-3). |
| q | string Free-text search across dispute/transaction/customer references. |
{- "data": [
- {
- "dispute_id": "6a12a61b-d612-4dc3-8c84-e4093662a9c8",
- "status": "draft",
- "original_transaction_id": "368700fc-be57-4411-8ef4-136caf5681c0",
- "original_clearing_record_id": "string",
- "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
- "chargeback_system": "mastercom",
- "reason_code": "fraud_unauthorized_card_not_present",
- "network_reason_code": "string",
- "reason": "string",
- "amount": 0.1,
- "currency": "string",
- "authorized_amount": 0.1,
- "network_chargeback_claim_ref": "string",
- "original_clearing_transaction_id": "string",
- "is_open": true,
- "is_settlement_pending": true,
- "network_chargeback_details": {
- "amount": 0.1,
- "currency": "string",
- "network_reason_code": "string",
- "is_partial_chargeback": true,
- "message_text": "string",
- "document_indicator": true,
- "credit_posted_as_purchase": true,
- "chargeback_id": "string",
- "reject_reason": "string"
}, - "settlement": {
- "state": "none",
- "latest_clearing_type": "refund",
- "net_amount": 0.1,
- "currency": "string",
- "last_settled_at": "2019-08-24T14:15:22Z"
}, - "network_settlement": [
- {
- "clearing_type": "refund",
- "network_transaction_ref": "string",
- "amount": 0.1,
- "currency": "string",
- "direction": "credit",
- "cleared_at": "2019-08-24T14:15:22Z"
}
], - "filing_window_days": 0,
- "required_documents": [
- "fraud_attestation"
], - "recommended_documents": [
- "fraud_attestation"
], - "documents": [
- {
- "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",
- "dispute_id": "6a12a61b-d612-4dc3-8c84-e4093662a9c8",
- "evidence_type": "fraud_attestation",
- "file_name": "string",
- "content_type": "application/pdf",
- "size_bytes": 0,
- "status": "pending",
- "network_document_ref": "string",
- "is_immutable": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "checklist": {
- "satisfied": true,
- "missing_required": [
- "fraud_attestation"
]
}
}
], - "checklist": {
- "satisfied": true,
- "missing_required": [
- "fraud_attestation"
]
}, - "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
], - "metadata": {
- "limit": 0,
- "page_size": 10,
- "page": 0,
- "total_pages": 0,
- "total": 0
}
}Retrieve one dispute, its status, and its evidence checklist state.
| dispute_id required | string <uuid> Dispute identifier in Open Fabric |
{- "dispute_id": "6a12a61b-d612-4dc3-8c84-e4093662a9c8",
- "status": "draft",
- "original_transaction_id": "368700fc-be57-4411-8ef4-136caf5681c0",
- "original_clearing_record_id": "string",
- "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
- "chargeback_system": "mastercom",
- "reason_code": "fraud_unauthorized_card_not_present",
- "network_reason_code": "string",
- "reason": "string",
- "amount": 0.1,
- "currency": "string",
- "authorized_amount": 0.1,
- "network_chargeback_claim_ref": "string",
- "original_clearing_transaction_id": "string",
- "is_open": true,
- "is_settlement_pending": true,
- "network_chargeback_details": {
- "amount": 0.1,
- "currency": "string",
- "network_reason_code": "string",
- "is_partial_chargeback": true,
- "message_text": "string",
- "document_indicator": true,
- "credit_posted_as_purchase": true,
- "chargeback_id": "string",
- "reject_reason": "string"
}, - "settlement": {
- "state": "none",
- "latest_clearing_type": "refund",
- "net_amount": 0.1,
- "currency": "string",
- "last_settled_at": "2019-08-24T14:15:22Z"
}, - "network_settlement": [
- {
- "clearing_type": "refund",
- "network_transaction_ref": "string",
- "amount": 0.1,
- "currency": "string",
- "direction": "credit",
- "cleared_at": "2019-08-24T14:15:22Z"
}
], - "filing_window_days": 0,
- "required_documents": [
- "fraud_attestation"
], - "recommended_documents": [
- "fraud_attestation"
], - "documents": [
- {
- "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",
- "dispute_id": "6a12a61b-d612-4dc3-8c84-e4093662a9c8",
- "evidence_type": "fraud_attestation",
- "file_name": "string",
- "content_type": "application/pdf",
- "size_bytes": 0,
- "status": "pending",
- "network_document_ref": "string",
- "is_immutable": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "checklist": {
- "satisfied": true,
- "missing_required": [
- "fraud_attestation"
]
}
}
], - "checklist": {
- "satisfied": true,
- "missing_required": [
- "fraud_attestation"
]
}, - "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}Update amount, currency, reason_code, or reason on a draft. Fails with 409 once the dispute has been submitted.
| dispute_id required | string <uuid> Dispute identifier in Open Fabric |
| amount | number <double> New disputed amount. |
| currency | string^[A-Z]{3}$ Must match the clearing record's currency (ISO 4217 Alpha-3). |
| reason_code | string (DisputeReasonCode) Enum: "fraud_unauthorized_card_not_present" "goods_not_received" "defective_not_as_described" "digital_goods_not_received" "refund_not_processed" "recurring_after_cancellation" "duplicate_processing" "incorrect_amount" OpenFabric reason code, mapped internally to the corresponding chargeback reason code with the card network. |
| reason | string <= 100 characters New cardholder statement. |
{- "amount": 0.1,
- "currency": "string",
- "reason_code": "fraud_unauthorized_card_not_present",
- "reason": "string"
}{- "dispute_id": "6a12a61b-d612-4dc3-8c84-e4093662a9c8",
- "status": "draft",
- "original_transaction_id": "368700fc-be57-4411-8ef4-136caf5681c0",
- "original_clearing_record_id": "string",
- "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
- "chargeback_system": "mastercom",
- "reason_code": "fraud_unauthorized_card_not_present",
- "network_reason_code": "string",
- "reason": "string",
- "amount": 0.1,
- "currency": "string",
- "authorized_amount": 0.1,
- "network_chargeback_claim_ref": "string",
- "original_clearing_transaction_id": "string",
- "is_open": true,
- "is_settlement_pending": true,
- "network_chargeback_details": {
- "amount": 0.1,
- "currency": "string",
- "network_reason_code": "string",
- "is_partial_chargeback": true,
- "message_text": "string",
- "document_indicator": true,
- "credit_posted_as_purchase": true,
- "chargeback_id": "string",
- "reject_reason": "string"
}, - "settlement": {
- "state": "none",
- "latest_clearing_type": "refund",
- "net_amount": 0.1,
- "currency": "string",
- "last_settled_at": "2019-08-24T14:15:22Z"
}, - "network_settlement": [
- {
- "clearing_type": "refund",
- "network_transaction_ref": "string",
- "amount": 0.1,
- "currency": "string",
- "direction": "credit",
- "cleared_at": "2019-08-24T14:15:22Z"
}
], - "filing_window_days": 0,
- "required_documents": [
- "fraud_attestation"
], - "recommended_documents": [
- "fraud_attestation"
], - "documents": [
- {
- "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",
- "dispute_id": "6a12a61b-d612-4dc3-8c84-e4093662a9c8",
- "evidence_type": "fraud_attestation",
- "file_name": "string",
- "content_type": "application/pdf",
- "size_bytes": 0,
- "status": "pending",
- "network_document_ref": "string",
- "is_immutable": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "checklist": {
- "satisfied": true,
- "missing_required": [
- "fraud_attestation"
]
}
}
], - "checklist": {
- "satisfied": true,
- "missing_required": [
- "fraud_attestation"
]
}, - "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}Files the chargeback with the card network — the only step in the dispute lifecycle that calls the network. Documents become immutable once this succeeds.
| dispute_id required | string <uuid> Dispute identifier in Open Fabric |
| Idempotency-Key | string Unique value submitted by the client to ensure an idempotent request when submitting a dispute. A retried request with the same key returns the cached response; a concurrent in-flight duplicate returns 409. |
{- "dispute_id": "6a12a61b-d612-4dc3-8c84-e4093662a9c8",
- "status": "draft",
- "original_transaction_id": "368700fc-be57-4411-8ef4-136caf5681c0",
- "original_clearing_record_id": "string",
- "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
- "chargeback_system": "mastercom",
- "reason_code": "fraud_unauthorized_card_not_present",
- "network_reason_code": "string",
- "reason": "string",
- "amount": 0.1,
- "currency": "string",
- "authorized_amount": 0.1,
- "network_chargeback_claim_ref": "string",
- "original_clearing_transaction_id": "string",
- "is_open": true,
- "is_settlement_pending": true,
- "network_chargeback_details": {
- "amount": 0.1,
- "currency": "string",
- "network_reason_code": "string",
- "is_partial_chargeback": true,
- "message_text": "string",
- "document_indicator": true,
- "credit_posted_as_purchase": true,
- "chargeback_id": "string",
- "reject_reason": "string"
}, - "settlement": {
- "state": "none",
- "latest_clearing_type": "refund",
- "net_amount": 0.1,
- "currency": "string",
- "last_settled_at": "2019-08-24T14:15:22Z"
}, - "network_settlement": [
- {
- "clearing_type": "refund",
- "network_transaction_ref": "string",
- "amount": 0.1,
- "currency": "string",
- "direction": "credit",
- "cleared_at": "2019-08-24T14:15:22Z"
}
], - "filing_window_days": 0,
- "required_documents": [
- "fraud_attestation"
], - "recommended_documents": [
- "fraud_attestation"
], - "documents": [
- {
- "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",
- "dispute_id": "6a12a61b-d612-4dc3-8c84-e4093662a9c8",
- "evidence_type": "fraud_attestation",
- "file_name": "string",
- "content_type": "application/pdf",
- "size_bytes": 0,
- "status": "pending",
- "network_document_ref": "string",
- "is_immutable": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "checklist": {
- "satisfied": true,
- "missing_required": [
- "fraud_attestation"
]
}
}
], - "checklist": {
- "satisfied": true,
- "missing_required": [
- "fraud_attestation"
]
}, - "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}Notification sent when a chargeback dispute's status changes (filed, network outcome synced via the status-sync poll, or closed).
| notification_id required | string <uuid> The unique identifier for the notification |
| type required | string Value: "v1:pba:dispute:updated" |
| created_at required | string <date-time> The creation timestamp of the notification in ISO 8601 format |
required | object (PbaDisputeUpdatedNotification) v1:pba:dispute:updated |
{- "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
- "type": "v1:pba:dispute:updated",
- "created_at": "2019-08-24T14:15:22Z",
- "data": {
- "card_program_id": "acba91e4-3ccc-44c0-89f3-673de52e33aa",
- "dispute_id": "6a12a61b-d612-4dc3-8c84-e4093662a9c8",
- "original_transaction_id": "368700fc-be57-4411-8ef4-136caf5681c0",
- "original_clearing_record_id": "string",
- "status": "draft",
- "is_open": true,
- "reason_code": "fraud_unauthorized_card_not_present",
- "network_chargeback_claim_ref": "string",
- "chargeback_id": "string",
- "updated_at": "2019-08-24T14:15:22Z"
}
}APIs to attach the documents a dispute's reason code requires, and to list, replace, or remove them while the dispute is still a draft.
See Manage evidence for which evidence each reason code accepts.
Call after successfully PUTting the file bytes to the upload_url from create/replace. Verifies the object landed in storage and flips the document from pending to uploaded. Draft only.
| dispute_id required | string <uuid> Dispute identifier in Open Fabric |
| document_id required | string <uuid> Evidence document identifier in Open Fabric |
{- "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",
- "dispute_id": "6a12a61b-d612-4dc3-8c84-e4093662a9c8",
- "evidence_type": "fraud_attestation",
- "file_name": "string",
- "content_type": "application/pdf",
- "size_bytes": 0,
- "status": "pending",
- "network_document_ref": "string",
- "is_immutable": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "checklist": {
- "satisfied": true,
- "missing_required": [
- "fraud_attestation"
]
}
}Mints a document in pending status plus a pre-signed upload_url — PUT the file bytes there directly (a Content-Type header matching content_type exactly), then call the complete endpoint. Rejects if evidence_type is not allowed for the reason code. Draft only. download_url isn't populated on this response.
| dispute_id required | string <uuid> Dispute identifier in Open Fabric |
| file_name required | string Original filename, including extension. |
| content_type required | string (EvidenceFileContentType) Enum: "application/pdf" "image/jpeg" "image/jp2" "image/tiff" "image/png" "image/heic" Accepted MIME type for an evidence document file. |
| size_bytes required | integer <= 14500000 Exact file size in bytes. Rejected with 400 if over the 14.5MB limit — before any bytes move. upload_url is signed for exactly this length, so a PUT of a different size fails. |
| evidence_type required | string (EvidenceType) Enum: "fraud_attestation" "expected_delivery_date" "proof_merchant_contacted" "proof_of_defect" "screenshots" "account_evidence" "merchant_comms" "proof_refund_promised" "cancellation_comms" "proof_of_cancellation" "cancellation_timestamp" "receipt_comparison" "receipt_or_invoice" Evidence document type. The set a given reason_code accepts is a subset of this list — see the required/recommended/allowed documents surfaced on the dispute (required_documents, recommended_documents) and rejected via 400 on upload if not allowed for the reason_code. |
{- "file_name": "string",
- "content_type": "application/pdf",
- "size_bytes": 14500000,
- "evidence_type": "fraud_attestation"
}{- "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",
- "dispute_id": "6a12a61b-d612-4dc3-8c84-e4093662a9c8",
- "evidence_type": "fraud_attestation",
- "file_name": "string",
- "content_type": "application/pdf",
- "size_bytes": 0,
- "status": "pending",
- "network_document_ref": "string",
- "is_immutable": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "checklist": {
- "satisfied": true,
- "missing_required": [
- "fraud_attestation"
]
}
}List the documents attached to a dispute, with the current checklist state. download_url isn't populated on list items.
| dispute_id required | string <uuid> Dispute identifier in Open Fabric |
{- "data": [
- {
- "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",
- "dispute_id": "6a12a61b-d612-4dc3-8c84-e4093662a9c8",
- "evidence_type": "fraud_attestation",
- "file_name": "string",
- "content_type": "application/pdf",
- "size_bytes": 0,
- "status": "pending",
- "network_document_ref": "string",
- "is_immutable": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "checklist": {
- "satisfied": true,
- "missing_required": [
- "fraud_attestation"
]
}
}
], - "checklist": {
- "satisfied": true,
- "missing_required": [
- "fraud_attestation"
]
}
}Returns document metadata plus a short-lived, pre-signed download_url.
| dispute_id required | string <uuid> Dispute identifier in Open Fabric |
| document_id required | string <uuid> Evidence document identifier in Open Fabric |
{- "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",
- "dispute_id": "6a12a61b-d612-4dc3-8c84-e4093662a9c8",
- "evidence_type": "fraud_attestation",
- "file_name": "string",
- "content_type": "application/pdf",
- "size_bytes": 0,
- "status": "pending",
- "network_document_ref": "string",
- "is_immutable": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "checklist": {
- "satisfied": true,
- "missing_required": [
- "fraud_attestation"
]
}
}Puts an existing document slot back into pending status plus a fresh pre-signed upload_url — PUT the new file bytes there directly (a Content-Type header matching content_type exactly), then call the complete endpoint. Draft only. download_url isn't populated on this response.
| dispute_id required | string <uuid> Dispute identifier in Open Fabric |
| document_id required | string <uuid> Evidence document identifier in Open Fabric |
| file_name required | string Original filename, including extension. |
| content_type required | string (EvidenceFileContentType) Enum: "application/pdf" "image/jpeg" "image/jp2" "image/tiff" "image/png" "image/heic" Accepted MIME type for an evidence document file. |
| size_bytes required | integer <= 14500000 Exact file size in bytes. Rejected with 400 if over the 14.5MB limit — before any bytes move. upload_url is signed for exactly this length, so a PUT of a different size fails. |
{- "file_name": "string",
- "content_type": "application/pdf",
- "size_bytes": 14500000
}{- "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",
- "dispute_id": "6a12a61b-d612-4dc3-8c84-e4093662a9c8",
- "evidence_type": "fraud_attestation",
- "file_name": "string",
- "content_type": "application/pdf",
- "size_bytes": 0,
- "status": "pending",
- "network_document_ref": "string",
- "is_immutable": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "checklist": {
- "satisfied": true,
- "missing_required": [
- "fraud_attestation"
]
}
}Only permitted while the dispute is in draft.
| dispute_id required | string <uuid> Dispute identifier in Open Fabric |
| document_id required | string <uuid> Evidence document identifier in Open Fabric |
{- "error_code": "string",
- "message": "string",
- "details": [
- {
- "error_code": "string",
- "message": "string",
- "param": "string",
- "reason_code": "string",
- "reason": "string"
}
]
}APIs to create and manage spend control rulesets.
See Manage Rulesets for implementation guidance.
Creates a new ruleset with optional embedded rules. Rule names are auto-generated using pattern {template_code}_{counter}.
| name required | string^[a-zA-Z0-9_-]+$ Ruleset name (alphanumeric with dash/underscore) |
| description | string Ruleset description |
| is_active | boolean Default: true Active status |
| is_default | boolean Default: false Set as tenant default ruleset |
| effective_from | string <date-time> Start date for effectiveness |
| effective_to | string <date-time> End date for effectiveness |
Array of objects (CreateRuleRequest) List of rules to create |
{- "name": "standard-account-limits",
- "description": "Default spending limits",
- "is_active": true,
- "is_default": true,
- "effective_from": "2026-03-17T03:45:40.745Z",
- "effective_to": "2026-03-17T03:45:40.745Z",
- "rules": [
- {
- "template_code": "currency_control",
- "description": "Only allow USD transactions",
- "parameters": {
- "allowed_currencies": [
- "USD"
]
}, - "violation_policy": "decline"
}, - {
- "template_code": "transaction_amount_limit",
- "description": "Limit each transaction to 250 USD",
- "parameters": {
- "limit_amount": 250,
- "currency": "USD"
}, - "violation_policy": "decline"
}
]
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
- "name": "string",
- "description": "string",
- "is_active": true,
- "is_default": true,
- "effective_from": "2019-08-24T14:15:22Z",
- "effective_to": "2019-08-24T14:15:22Z",
- "rules": [
- {
- "name": "string",
- "template_code": "account_billing_amount_limit",
- "description": "string",
- "parameters": { },
- "conditions": { },
- "violation_policy": "decline",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
], - "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}Lists all rulesets for the tenant with pagination support.
| is_active | boolean Filter by active status |
| page | integer Default: 1 Page number |
| limit | integer <= 100 Default: 20 Results per page |
{- "data": [
- {
- "id": "019cfa07-6b83-7950-b126-7e94f4477dff",
- "name": "standard-account-limits",
- "description": "Default spending limits",
- "is_active": true,
- "is_default": true,
- "rules_count": 4,
- "created_at": "2026-03-17T03:45:40.745Z",
- "updated_at": "2026-03-17T03:45:40.745Z"
}, - {
- "id": "019cfa3f-424b-764c-8476-36132e57f603",
- "name": "premium-users",
- "description": "Premium users spending limits",
- "is_active": true,
- "is_default": false,
- "rules_count": 2,
- "created_at": "2026-03-17T03:45:40.745Z",
- "updated_at": "2026-03-17T03:45:40.745Z"
}
], - "pagination": {
- "total": 2,
- "page": 1,
- "limit": 20
}
}Retrieves a specific ruleset by ID with all its rules.
| ruleset_id required | string <uuid> Ruleset identifier (UUID) |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
- "name": "string",
- "description": "string",
- "is_active": true,
- "is_default": true,
- "effective_from": "2019-08-24T14:15:22Z",
- "effective_to": "2019-08-24T14:15:22Z",
- "rules": [
- {
- "name": "string",
- "template_code": "account_billing_amount_limit",
- "description": "string",
- "parameters": { },
- "conditions": { },
- "violation_policy": "decline",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
], - "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}Updates ruleset metadata and manages rules. Rules can be added, updated, or removed in a single request.
| ruleset_id required | string <uuid> Ruleset identifier (UUID) |
| name | string^[a-zA-Z0-9_-]+$ Updated ruleset name |
| description | string Updated description |
| is_active | boolean Updated active status |
| is_default | boolean Set as tenant default ruleset |
| effective_from | string <date-time> Updated start date |
| effective_to | string <date-time> Updated end date |
object (RuleModifications) Rule modifications for update request |
{- "is_default": true
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
- "name": "string",
- "description": "string",
- "is_active": true,
- "is_default": true,
- "effective_from": "2019-08-24T14:15:22Z",
- "effective_to": "2019-08-24T14:15:22Z",
- "rules": [
- {
- "name": "string",
- "template_code": "account_billing_amount_limit",
- "description": "string",
- "parameters": { },
- "conditions": { },
- "violation_policy": "decline",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
], - "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}Deletes a ruleset by ID.
| ruleset_id required | string <uuid> Ruleset identifier (UUID) |
{- "error_code": "string",
- "message": "string",
- "details": [
- {
- "error_code": "string",
- "message": "string",
- "param": "string",
- "reason_code": "string",
- "reason": "string"
}
]
}APIs to assign spend control rulesets to accounts and tokens.
See Ruleset Assignment for implementation guidance.
Assigns a ruleset to a customer account with a specific scope definition.
| account_id required | string <uuid> Account identifier in Open Fabric |
| ruleset_id required | string <uuid> Ruleset identifier |
required | object (RulesetScope) Scope definition for ruleset assignment |
{- "ruleset_id": "ca688a19-2766-4b2c-aefa-28d16a464773",
- "scope": {
- "level": "account",
- "provision_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "provision_types": [
- "customer_account_device"
]
}
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
- "ruleset_id": "ca688a19-2766-4b2c-aefa-28d16a464773",
- "scope": {
- "level": "account",
- "provision_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "provision_types": [
- "customer_account_device"
]
}, - "created_at": "2019-08-24T14:15:22Z"
}Lists all rulesets assigned to an account.
| account_id required | string <uuid> Account identifier in Open Fabric |
| level | string (AuthPolicyRulesetScopeLevel) Enum: "account" "token" Filter by scope level |
{- "data": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
- "ruleset": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "is_active": true
}, - "scope": {
- "level": "account",
- "provision_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "provision_types": [
- "customer_account_device"
]
}, - "created_at": "2019-08-24T14:15:22Z"
}
]
}Updates an existing ruleset assignment for an account.
| account_id required | string <uuid> Account identifier in Open Fabric |
| assignment_id required | string <uuid> Assignment identifier |
| ruleset_id required | string <uuid> Ruleset identifier |
required | object (RulesetScope) Scope definition for ruleset assignment |
{- "ruleset_id": "ca688a19-2766-4b2c-aefa-28d16a464773",
- "scope": {
- "level": "account",
- "provision_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "provision_types": [
- "customer_account_device"
]
}
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
- "ruleset_id": "ca688a19-2766-4b2c-aefa-28d16a464773",
- "scope": {
- "level": "account",
- "provision_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "provision_types": [
- "customer_account_device"
]
}, - "created_at": "2019-08-24T14:15:22Z"
}Removes a ruleset assignment from an account.
| account_id required | string <uuid> Account identifier in Open Fabric |
| assignment_id required | string <uuid> Assignment identifier |
{- "error_code": "string",
- "message": "string",
- "details": [
- {
- "error_code": "string",
- "message": "string",
- "param": "string",
- "reason_code": "string",
- "reason": "string"
}
]
}APIs you use to approve/decline and query transactions during online orchestration.
See Orchestrated integration guide for the end-to-end flow.
Open Fabric calls your backend to create a transaction request after a customer selects your payment method at checkout.
You return a response containing a redirect_url to your approval flow and gateway URLs used to redirect the customer back to checkout.
| tenant_partner_id required | string Reference ID to identify Partner on Tenant system |
| fabric_reference_id required | string OpenFabric Generated ID for this Transaction - UUID |
| partner_reference_id required | string Transaction ID set by Partner and sent to OpenFabric |
| tenant_id required | string <uuid> OpenFabric Generated ID for your Tenant account - UUID |
| gateway_success_url required | string <uri> This is the URL Tenant should redirect customers to when the transaction is successfully approved by Tenant |
| gateway_fail_url required | string <uri> This is the URL Tenant should redirect Customers to when the transaction is declined by Tenant. The transaction could be declined, because the customer cancelled the transaction on Tenant's payment flow or the Tenant simply declined to approve this transaction |
object (CustomerInfo) OpenFabric collects the below customer Info Collection from merchants. We will pass-through the collected info to Tenant | |
| amount required | number Transaction amount for which Tenant's authorization is requested |
| currency required | string = 3 characters ^[A-Z]*$ Transaction Currency for which Tenant's authorization is requested (ISO 4217 Alpha-3 currency codes) |
required | object (TransactionDetails) Transaction Details sent by Partner. |
object (PatLinkInfo) | |
| partner_name | string Partner name |
| source | string Source of transaction request |
{- "tenant_partner_id": "27666828-57f9-4709-a9a9-84167e091f5f",
- "fabric_reference_id": "ff0398e5-d045-441f-b130-bcd517964775",
- "partner_reference_id": "P1293201980299030",
- "tenant_id": "00fcf093-71fb-4349-8c0b-de810480d6b1",
- "customer_info": {
- "mobile_number": "+6587654321",
- "email": "developer@bnpl1.com",
- "first_name": "BNPL",
- "middle_name": "string",
- "last_name": "Developer",
- "country": "string",
- "country_code": "st",
- "partner_reference_id": "cd992711-498f-47be-b636-cf2e3eaad935"
}, - "amount": 120.1,
- "currency": "SGD",
- "transaction_details": {
- "shipping_address": {
- "address_line_1": "80 Robinson Road",
- "address_line_2": "#09-01",
- "address_line_3": "#09-01",
- "district": "string",
- "city": "string",
- "state": "string",
- "post_code": "068898",
- "country": "Singapore",
- "country_code": "SG",
- "phone_number": "string",
- "masked_phone_number": "string",
- "masked_email": "string",
- "self_pickup": true
}, - "billing_address": {
- "address_line_1": "80 Robinson Road",
- "address_line_2": "#09-01",
- "address_line_3": "#09-01",
- "district": "string",
- "city": "string",
- "state": "string",
- "post_code": "068898",
- "country": "Singapore",
- "country_code": "SG",
- "phone_number": "string",
- "masked_phone_number": "string",
- "masked_email": "string",
- "self_pickup": true
}, - "items": [
- {
- "item_id": "P100",
- "name": "iPhone",
- "variation_name": "Black, 128GB",
- "description": "string",
- "quantity": 1,
- "price": 11020,
- "original_price": 12020,
- "discount_amount": 0,
- "amount": 0,
- "tax_amount": 0,
- "tax_code": "string",
- "categories": [
- "Electronics"
], - "item_url": "string",
- "item_image_url": "string",
- "seller_info": {
- "seller_id": "string",
- "seller_name": "string",
- "email": "string",
- "phone": "string",
- "url": "string",
- "seller_address": "string"
}
}, - {
- "item_id": "P101",
- "name": "iPhone SE case",
- "price": 1000,
- "quantity": 1,
- "variation_name": "White",
- "categories": [
- "Accessories"
]
}
], - "original_amount": 13020,
- "tax_amount": 390.6,
- "shipping_amount": 1020,
- "voucher_code": "string",
- "fees": {
- "description": "string",
- "amount": 0
}, - "refundable_amount": 0,
- "additional_info": { },
- "expiry_date": "2019-08-24T14:15:22Z"
}, - "pat_link": {
- "link_id": "02a2c2f0-9521-47cc-9615-2e177adeebac",
- "tenant_link_ref": "string",
- "partner_link_ref": "string"
}, - "partner_name": "string",
- "source": "string"
}{- "tenant_reference_id": "cd992711-498f-47be-b636-cf2e3eaad935",
- "status": "approved",
- "reason": "string"
}Tenant can call this API to approve or fail a transaction.
Open Fabric will create a Transaction with the default state created. Tenant can update the transaction to approved or failed.
| tenant_reference_id required | string >= 4 characters ^[a-zA-Z0-9\-_@\.]*$ Transaction ID in Tenant system. This is the same transaction ID that Tenant shared as part of the above step |
| status required | string (TransactionApprovalStatus) Enum: "approved" "failed" Tenant can either Approve or Fail a transaction. In case of Failed, reason is mandatory. |
| approved_amount | number Approved transaction amount |
| approved_currency | string = 3 characters ^[A-Z]*$ Approved transaction Currency (ISO 4217 Alpha-3 currency codes) |
| reason | string |
{- "tenant_reference_id": "cd992711-498f-47be-b636-cf2e3eaad935",
- "status": "approved"
}{- "error_code": "string",
- "message": "string",
- "details": [
- {
- "error_code": "string",
- "message": "string",
- "param": "string",
- "reason_code": "string",
- "reason": "string"
}
]
}This API can be used to fetch a transaction
| id required | string <uuid> OpenFabric Generated ID for this Transaction. You will receive this part of Update Transaction Response. |
{- "id": "ff0398e5-d045-441f-b130-bcd517964775",
- "partner_reference_id": "P1293201980299030",
- "tenant_reference_id": "cd992711-498f-47be-b636-cf2e3eaad935",
- "tenant_partner_id": "27666828-57f9-4709-a9a9-84167e091f5f",
- "tenant_id": "00fcf093-71fb-4349-8c0b-de810480d6b1",
- "partner_id": "9bde4fbf-893b-49f9-b7b3-4079a76bb362",
- "partner_name": "Lazada",
- "customer_id": "88db7aa7-2cdd-42cc-9827-8d46f936ef79",
- "partner_redirect_success_url": "http://sample-merchant-flow.openfabric.co?id=f0398e5-d045-441f-b130-bcd517964775&state=PAID",
- "partner_redirect_fail_url": "http://sample-merchant-flow.openfabric.co?id=f0398e5-d045-441f-b130-bcd517964775&state=CANCELLED",
- "gateway_success_url": "http://of-gateway.s3-website-ap-southeast-1.amazonaws.com?reference_id=P1293201980299030&state=PAID",
- "customer_info": {
- "mobile_number": "+6587654321",
- "first_name": "postpebnpl",
- "last_name": "developer",
- "country": "Singapore",
- "country_code": "SG",
- "email": "developer@bnpl1.com"
}, - "amount": 120.1,
- "currency": "SGD",
- "status": "created",
- "card_reference_id": "7743087",
- "created_at": "2021-11-06T04:26:47.450Z",
- "updated_at": "2021-11-06T04:26:47.450Z"
}This API can be used to fetch transaction with all details including card, customer and transaction information submitted by Partner.
| id required | string <uuid> OpenFabric Generated ID for this Transaction. You will receive this part of Update Transaction Response. |
{- "id": "ff0398e5-d045-441f-b130-bcd517964775",
- "partner_reference_id": "P1293201980299030",
- "tenant_reference_id": "Tenant-cd992711-498f-47be-b636-cf2e3eaad935",
- "tenant_partner_id": "27666828-57f9-4709-a9a9-84167e091f5f",
- "tenant_id": "00fcf093-71fb-4349-8c0b-de810480d6b1",
- "partner_id": "9bde4fbf-893b-49f9-b7b3-4079a76bb362",
- "partner_name": "Lazada",
- "partner_redirect_success_url": "http://sample-merchant-flow.openfabric.co?id=f0398e5-d045-441f-b130-bcd517964775&state=PAID",
- "partner_redirect_fail_url": "http://sample-merchant-flow.openfabric.co?id=f0398e5-d045-441f-b130-bcd517964775&state=CANCELLED",
- "gateway_success_url": "http://of-gateway.s3-website-ap-southeast-1.amazonaws.com?reference_id=P1293201980299030&state=PAID",
- "card": {
- "id": "62f321a3-7f34-4a18-a556-9e00fdc22467",
- "customer_id": "62f321a3-7f34-4a18-a556-9e00fdc22467",
- "redacted_number": "1111",
- "country": "USA",
- "country_code": "US"
}, - "customer_id": "88db7aa7-2cdd-42cc-9827-8d46f936ef79",
- "customer_info": {
- "mobile_number": "+6587654321",
- "first_name": "postpebnpl",
- "last_name": "developer",
- "country": "Singapore",
- "country_code": "SG",
- "email": "developer@bnpl1.com"
}, - "amount": 120.1,
- "currency": "SGD",
- "status": "failed",
- "card_reference_id": "7743087",
- "created_at": "2021-11-06T04:26:47.450Z",
- "updated_at": "2021-11-06T04:26:47.450Z",
- "transaction_details": {
- "shipping_address": {
- "country": "Singapore",
- "country_code": "SG",
- "address_line_1": "80 Robinson Road",
- "address_line_2": "#09-01",
- "address_line_3": "#09-01",
- "post_code": "068898"
}, - "billing_address": {
- "country": "Singapore",
- "country_code": "SG",
- "address_line_1": "80 Robinson Road",
- "address_line_2": "#09-01",
- "address_line_3": "#09-01",
- "post_code": "068898"
}, - "items": [
- {
- "item_id": "P100",
- "name": "iPhone",
- "price": 11020,
- "quantity": 1,
- "variation_name": "Black, 128GB",
- "original_price": 12020,
- "categories": [
- "Electronics"
]
}, - {
- "item_id": "P101",
- "name": "iPhone SE case",
- "price": 1000,
- "quantity": 1,
- "variation_name": "White",
- "categories": [
- "Accessories"
]
}
], - "tax_amount": 390.6,
- "shipping_amount": 1020,
- "original_amount": 13020
}
}Callback sent to your backend after a one-time payment credential is charged successfully.
| notification_id | string <uuid> ID of the notification |
| type required | string Value: "transaction:charged" type of notification |
| created_at required | string <date-time> |
required | object (schemas-AccountTransactionChargedNotification) Notification for transaction charge |
[- {
- "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
- "type": "transaction:charged",
- "created_at": "2019-08-24T14:15:22Z",
- "data": {
- "transaction_id": "cd992711-498f-47be-b636-cf2e3eaad936",
- "tenant_reference_id": "BNPL123456890",
- "status": "charged",
- "charged_at": "2021-11-06T04:26:47.450Z"
}
}
]Callback sent to your backend when a reversal or refund is issued against a one-time payment credential.
| notification_id | string <uuid> ID of the notification |
| type required | string Value: "transaction:reversed" type of notification |
| created_at required | string <date-time> |
required | object (schemas-AccountTransactionReversedNotification) |
[- {
- "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
- "type": "transaction:reversed",
- "created_at": "2019-08-24T14:15:22Z",
- "data": {
- "transaction_id": "cd992711-498f-47be-b636-cf2e3eaad936",
- "tenant_reference_id": "BNPL123456890",
- "status": "reversed",
- "reversed_at": "2021-11-06T04:26:47.450Z",
- "reversed_amount": 7500,
- "action_type": "reversal"
}
}
]Callback sent to your backend when a transaction is credited.
| notification_id | string <uuid> ID of the notification |
| type required | string Value: "transaction:credited" type of notification |
| created_at required | string <date-time> |
required | object (schemas-AccountTransactionCreditedNotification) |
[- {
- "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
- "type": "transaction:credited",
- "created_at": "2019-08-24T14:15:22Z",
- "data": {
- "transaction_id": "cd992711-498f-47be-b636-cf2e3eaad936",
- "tenant_customer_ref": "CUS23432898",
- "tenant_link_ref": "PM-1293201980299030",
- "status": "credited",
- "credited_at": "2021-11-06T04:26:47.450Z",
- "credited_amount": 7500,
- "currency": "PHP",
- "billing_credited_amount": 134.75,
- "billing_currency": "USD",
- "network_transaction_time": "2021-11-04T00:00:00Z",
- "network_merchant_category_code": "5812",
- "network_merchant_id": "W2E7JYS5UGIYXN1",
- "network_merchant_name": "WWW.EMBARKLABS.ORG",
- "network_merchant_outlet_address": "+6586866171 SG"
}
}
]APIs to manage your callback (webhook) subscriptions for online-orchestration updates.
{- "value": {
- "id": "cd992711-498f-47be-b636-cf2e3eaad935",
- "tenant_id": "00fcf093-71fb-4349-8c0b-de810480d6b1",
- "type": "webhook",
- "subscribed_events": [
- "*"
], - "config": {
- "authConfig": {
- "header": "X-API-Key",
- "value": "HxMrzQBFbaDeLkUar87nczWNi"
}
}
}
}Create a webhook subscription for Tenant
| webhook_type | string (WebhookType) Enum: "online" "pat_provision" Webhook type |
Notification subscription object to init
| config required | object Configuration options for the subscription |
| subscribed_events required | Array of strings |
{- "type": "webhook",
- "subscribed_events": [
- "*"
], - "config": {
- "authConfig": {
- "header": "X-API-Key",
- "value": "HxMrzQBFbaDeLkUar87nczWNi"
}
}
}{- "id": "cd992711-498f-47be-b636-cf2e3eaad935",
- "tenant_id": "00fcf093-71fb-4349-8c0b-de810480d6b1",
- "type": "webhook",
- "subscribed_events": [
- "*"
], - "config": {
- "authConfig": {
- "header": "X-API-Key",
- "value": "HxMrzQBFbaDeLkUar87nczWNi"
}
}
}Update an existing webhook subscription for Tenant
| id required | string <uuid> ID of an existing notification subscription |
| webhook_type | string (WebhookType) Enum: "online" "pat_provision" Webhook type |
Notification subscription object to update
| config required | object Configuration options for the subscription |
| subscribed_events required | Array of strings |
{- "type": "webhook",
- "subscribed_events": [
- "*"
], - "config": {
- "authConfig": {
- "header": "X-API-Key",
- "value": "HxMrzQBFbaDeLkUar87nczWNi"
}
}
}{- "id": "cd992711-498f-47be-b636-cf2e3eaad935",
- "tenant_id": "00fcf093-71fb-4349-8c0b-de810480d6b1",
- "type": "webhook",
- "subscribed_events": [
- "*"
], - "config": {
- "authConfig": {
- "header": "X-API-Key",
- "value": "HxMrzQBFbaDeLkUar87nczWNi"
}
}
}List the tenant's webhook endpoints, every type and status by default. No credential or signing key is returned.
| webhook_type | Array of strings (WebhookEndpointType) Items Enum: "issuing_event" "issuing_ledger" "issuing_authorization" "issuing_three_ds" "online_txn" "online_event" "pat_event" Filter by one or more webhook types; repeat the parameter for each. Omitted means every type. |
| status | string (WebhookEndpointStatus) Enum: "active" "inactive" Filter by status. Omitted means both. |
| page | integer >= 1 Current page (>= 1). |
| page_size | integer [ 10 .. 100 ] Number of records per page (10-100). |
| sort | string Example: sort=-created_at Sorting conditions, for example -created_at or +name. |
{- "data": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
- "name": "string",
- "webhook_type": "issuing_event",
- "auth": {
- "type": "none",
- "header_name": "string",
- "username": "string",
- "client_id": "string",
- "scopes": [
- "string"
], - "audience": "string",
- "client_auth": "client_secret_post",
- "key_thumbprint": "string",
- "token_path": "string",
- "expires_in_path": "string",
- "token_ttl_seconds": 0,
- "token_type": "string",
- "has_secret": true,
- "api_key_hint": "string",
- "client_secret_hint": "string"
}, - "signing": {
- "algorithm": "hmac_sha256",
- "string_to_sign": "string",
- "timestamp_format": "string",
- "signature_encoding": "hex",
- "headers": {
- "property1": "string",
- "property2": "string"
}, - "key_id": "string",
- "canonical_body": "none",
- "response_verification": {
- "algorithm": "rsa_sha256",
- "public_key": "string",
- "signature_header": "string",
- "signature_pattern": "string",
- "timestamp_header": "string",
- "key_id_header": "string",
- "string_to_verify": "string",
- "signature_encoding": "hex"
}, - "has_secret": true
}, - "custom_headers": [
- {
- "name": "string",
- "value": "string"
}
], - "subscribed_events": [
- "string"
], - "card_program_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "status": "active",
- "last_test": {
- "tested_at": "2019-08-24T14:15:22Z",
- "all_reachable": true
}, - "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
], - "metadata": {
- "limit": 0,
- "page_size": 10,
- "page": 0,
- "total_pages": 0,
- "total": 0
}
}Create one webhook endpoint of any webhook type. A single-record type (authorization, 3D Secure, ledger) has one active default endpoint and may add active overrides for card programs, each card program in at most one override; a URL another active endpoint of the same type already uses is refused. Credentials are encrypted on write. An authorization or 3D Secure record is verified with the adapter before it is stored.
| name | string Defaults to the host of the record's first URL. |
| webhook_type required | string (WebhookEndpointType) Enum: "issuing_event" "issuing_ledger" "issuing_authorization" "issuing_three_ds" "online_txn" "online_event" "pat_event" The outbound flow an endpoint serves. issuing_ledger, issuing_authorization, issuing_three_ds and online_txn allow one active endpoint per tenant; the notification types (issuing_event, online_event, pat_event) allow many. |
required | WebhookUrlConfig (object) or WebhookLedgerConfig (object) or WebhookAuthorizationConfig (object) or (WebhookThreeDsConfig (WebhookThreeDsOtpConfig (object) or WebhookThreeDsOobConfig (object))) (WebhookEndpointConfig) Endpoint config, typed by |
required | WebhookAuthNone (object) or WebhookAuthApiKeyCreate (object) or WebhookAuthBasicCreate (object) or WebhookAuthOAuth2ClientSecretCreate (object) or WebhookAuthOAuth2PrivateKeyJwtCreate (object) or WebhookAuthLoginTokenCreate (object) (WebhookEndpointAuthCreate) Authentication on create. Each variant extends its update-time base and also requires the credential. OAuth2 has one variant per client-auth method, so this union is a plain oneOf rather than a discriminated one. |
WebhookSigningHmacCreate (object) or WebhookSigningRsaCreate (object) (WebhookEndpointSigningCreate) Signing on create. The variant for the algorithm also requires its key. | |
Array of WebhookCustomHeaderLiteral (object) or WebhookCustomHeaderPayloadPath (object) (WebhookCustomHeader) | |
| subscribed_events | Array of strings non-empty [ items^(\*|[a-z0-9_-]+(:[a-z0-9_-]+)*(:\*)?)$ ] Notification webhook types only, and then required. Each value is an exact member of
the type's event enum, a group wildcard such as |
| card_program_ids | Array of strings <uuid> [ items <uuid > ] Default: [] Card programs this endpoint is scoped to, each an active card program of the tenant. For notification endpoints it filters which events are delivered; empty or absent receives every event. For authorization, 3DS and ledger endpoints an empty list marks the default endpoint, and a non-empty list makes the endpoint an override for those card programs, used instead of the default. A card program can be in only one active override per webhook type. |
{- "name": "string",
- "webhook_type": "issuing_event",
- "auth": {
- "type": "none"
}, - "signing": {
- "algorithm": "hmac_sha256",
- "string_to_sign": "string",
- "timestamp_format": "string",
- "signature_encoding": "hex",
- "headers": {
- "property1": "string",
- "property2": "string"
}, - "key_id": "string",
- "canonical_body": "none",
- "hmac_key": "string",
- "private_key": "string",
- "response_verification": {
- "algorithm": "rsa_sha256",
- "public_key": "string",
- "signature_header": "string",
- "signature_pattern": "string",
- "timestamp_header": "string",
- "key_id_header": "string",
- "string_to_verify": "string",
- "signature_encoding": "hex"
}
}, - "custom_headers": [
- {
- "name": "string",
- "value": "string"
}
], - "subscribed_events": [
- "string"
], - "card_program_ids": [ ]
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
- "name": "string",
- "webhook_type": "issuing_event",
- "auth": {
- "type": "none",
- "header_name": "string",
- "username": "string",
- "client_id": "string",
- "scopes": [
- "string"
], - "audience": "string",
- "client_auth": "client_secret_post",
- "key_thumbprint": "string",
- "token_path": "string",
- "expires_in_path": "string",
- "token_ttl_seconds": 0,
- "token_type": "string",
- "has_secret": true,
- "api_key_hint": "string",
- "client_secret_hint": "string"
}, - "signing": {
- "algorithm": "hmac_sha256",
- "string_to_sign": "string",
- "timestamp_format": "string",
- "signature_encoding": "hex",
- "headers": {
- "property1": "string",
- "property2": "string"
}, - "key_id": "string",
- "canonical_body": "none",
- "response_verification": {
- "algorithm": "rsa_sha256",
- "public_key": "string",
- "signature_header": "string",
- "signature_pattern": "string",
- "timestamp_header": "string",
- "key_id_header": "string",
- "string_to_verify": "string",
- "signature_encoding": "hex"
}, - "has_secret": true
}, - "custom_headers": [
- {
- "name": "string",
- "value": "string"
}
], - "subscribed_events": [
- "string"
], - "card_program_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "status": "active",
- "last_test": {
- "tested_at": "2019-08-24T14:15:22Z",
- "all_reachable": true
}, - "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}Every event Open Fabric can send for a notification webhook type, with each group's wildcard token. All are selectable; one with no publisher yet starts being delivered when one ships.
| webhook_type required | string (WebhookNotificationType) Enum: "issuing_event" "online_event" "pat_event" Which notification webhook type's events to list. |
{- "events": [
- {
- "event": "string",
- "group": "string",
- "description": "string",
- "recommended": true
}
], - "groups": [
- {
- "group": "string",
- "wildcard": "string"
}
]
}Everything the builder needs for one key in one call: the schema the catalogue was derived from and the catalogue itself, which is the source picker. The default payload is the identity mapping over these fields, so nothing else seeds the builder.
| webhook_type required | string (WebhookEndpointType) Enum: "issuing_event" "issuing_ledger" "issuing_authorization" "issuing_three_ds" "online_txn" "online_event" "pat_event" The outbound flow an endpoint serves. issuing_ledger, issuing_authorization, issuing_three_ds and online_txn allow one active endpoint per tenant; the notification types (issuing_event, online_event, pat_event) allow many. |
| key required | string The payload key - an event type, a ledger operation, pre_auth, final_auth, otp, oob_challenge or create_online_txn. |
{- "webhook_type": "issuing_event",
- "key": "string",
- "source_schema": "string",
- "catalogue_version": "string",
- "fields": [
- {
- "path": "string",
- "type": "string",
- "required": true,
- "removable": true,
- "array_of": "string",
- "description": "string"
}
]
}Retrieve one webhook endpoint. No credential or signing key is returned.
| id required | string <uuid> ID of an existing webhook endpoint. |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
- "name": "string",
- "webhook_type": "issuing_event",
- "auth": {
- "type": "none",
- "header_name": "string",
- "username": "string",
- "client_id": "string",
- "scopes": [
- "string"
], - "audience": "string",
- "client_auth": "client_secret_post",
- "key_thumbprint": "string",
- "token_path": "string",
- "expires_in_path": "string",
- "token_ttl_seconds": 0,
- "token_type": "string",
- "has_secret": true,
- "api_key_hint": "string",
- "client_secret_hint": "string"
}, - "signing": {
- "algorithm": "hmac_sha256",
- "string_to_sign": "string",
- "timestamp_format": "string",
- "signature_encoding": "hex",
- "headers": {
- "property1": "string",
- "property2": "string"
}, - "key_id": "string",
- "canonical_body": "none",
- "response_verification": {
- "algorithm": "rsa_sha256",
- "public_key": "string",
- "signature_header": "string",
- "signature_pattern": "string",
- "timestamp_header": "string",
- "key_id_header": "string",
- "string_to_verify": "string",
- "signature_encoding": "hex"
}, - "has_secret": true
}, - "custom_headers": [
- {
- "name": "string",
- "value": "string"
}
], - "subscribed_events": [
- "string"
], - "card_program_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "status": "active",
- "last_test": {
- "tested_at": "2019-08-24T14:15:22Z",
- "all_reachable": true
}, - "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}Patch an endpoint. The webhook type is immutable and config is merged field by field. An omitted credential is kept. Deactivating takes effect on the adapter's next call. The authorization record cannot be deactivated, but its pre_auth_url may be cleared, after which pre-authorizations fall back to final_auth_url.
| id required | string <uuid> ID of an existing webhook endpoint. |
| name | string |
object (WebhookEndpointConfigPatch) non-empty Partial config on update, merged field by field into the stored record. Every field of
every webhook type is optional here because | |
object (WebhookEndpointAuth) Authentication settings on update, one variant per type. Each variant is the base its create-time counterpart extends, so the credential is optional here: the block replaces the stored one as a whole and an omitted secret keeps the stored value. Secrets are encrypted on write and never returned. | |
WebhookEndpointSigning (object) or (WebhookSigningRemoval (object or null)) (WebhookEndpointSigningUpdate) On update a full profile replaces the stored one and null removes it. | |
Array of WebhookCustomHeaderLiteral (object) or WebhookCustomHeaderPayloadPath (object) (WebhookCustomHeader) Replaces the stored list. Send an empty array to remove every custom header. | |
| subscribed_events | Array of strings non-empty [ items^(\*|[a-z0-9_-]+(:[a-z0-9_-]+)*(:\*)?)$ ] |
| card_program_ids | Array of strings or null <uuid> [ items <uuid > ] Replaces the stored list of card programs; omit the field to keep it. Null or an empty array means every card program for notification endpoints and the default endpoint for authorization, 3DS and ledger endpoints. |
| status | string (WebhookEndpointStatus) Enum: "active" "inactive" An inactive endpoint stops being called. The issuing_authorization record cannot be made inactive. |
{- "name": "string",
- "config": {
- "authorization_mode": "pre_auth_and_final_auth",
}, - "auth": {
- "type": "none"
}, - "signing": {
- "algorithm": "hmac_sha256",
- "string_to_sign": "string",
- "timestamp_format": "string",
- "signature_encoding": "hex",
- "headers": {
- "property1": "string",
- "property2": "string"
}, - "key_id": "string",
- "canonical_body": "none",
- "hmac_key": "string",
- "private_key": "string",
- "response_verification": {
- "algorithm": "rsa_sha256",
- "public_key": "string",
- "signature_header": "string",
- "signature_pattern": "string",
- "timestamp_header": "string",
- "key_id_header": "string",
- "string_to_verify": "string",
- "signature_encoding": "hex"
}
}, - "custom_headers": [
- {
- "name": "string",
- "value": "string"
}
], - "subscribed_events": [
- "string"
], - "card_program_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "status": "active"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
- "name": "string",
- "webhook_type": "issuing_event",
- "auth": {
- "type": "none",
- "header_name": "string",
- "username": "string",
- "client_id": "string",
- "scopes": [
- "string"
], - "audience": "string",
- "client_auth": "client_secret_post",
- "key_thumbprint": "string",
- "token_path": "string",
- "expires_in_path": "string",
- "token_ttl_seconds": 0,
- "token_type": "string",
- "has_secret": true,
- "api_key_hint": "string",
- "client_secret_hint": "string"
}, - "signing": {
- "algorithm": "hmac_sha256",
- "string_to_sign": "string",
- "timestamp_format": "string",
- "signature_encoding": "hex",
- "headers": {
- "property1": "string",
- "property2": "string"
}, - "key_id": "string",
- "canonical_body": "none",
- "response_verification": {
- "algorithm": "rsa_sha256",
- "public_key": "string",
- "signature_header": "string",
- "signature_pattern": "string",
- "timestamp_header": "string",
- "key_id_header": "string",
- "string_to_verify": "string",
- "signature_encoding": "hex"
}, - "has_secret": true
}, - "custom_headers": [
- {
- "name": "string",
- "value": "string"
}
], - "subscribed_events": [
- "string"
], - "card_program_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "status": "active",
- "last_test": {
- "tested_at": "2019-08-24T14:15:22Z",
- "all_reachable": true
}, - "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}Remove an endpoint and its payload mappings; the audit trail keeps what it was. The authorization record cannot be deleted.
| id required | string <uuid> ID of an existing webhook endpoint. |
{- "error_code": "string",
- "message": "string",
- "details": [
- {
- "error_code": "string",
- "message": "string",
- "param": "string",
- "reason_code": "string",
- "reason": "string"
}
]
}Probe every configured URL: resolve the host, complete the TLS handshake, obtain a token where configured, and send a bodiless OPTIONS request carrying the endpoint's auth header and literal custom headers, with one HEAD fallback when the OPTIONS is answered without an Allow header. Nothing is signed and no body is sent, so nothing reaches a ledger, authorization or 3D Secure system that it could act on. The URL may answer with any status code; 401 or 403 reports the credential as rejected, and an Allow header that excludes POST reports method_not_allowed. Staff may run it, being the one endpoint action that changes no config.
| id required | string <uuid> ID of an existing webhook endpoint. |
{- "results": [
- {
- "target": "string",
- "reachable": true,
- "status_code": 0,
- "duration_ms": 0,
- "failure_reason": "dns_error",
- "token_obtained": true,
- "sent_headers": {
- "property1": "string",
- "property2": "string"
}, - "response_body_excerpt": "string"
}
], - "tested_at": "2019-08-24T14:15:22Z"
}One endpoint's mappings plus available_keys, the keys it can receive right now. Every receivable key normally has a mapping (a default snapshot at least); a listed mapping whose key is not in available_keys is stale.
| id required | string <uuid> ID of an existing webhook endpoint. |
{- "data": [
- {
- "endpoint_id": "e9ce0d4f-d433-423d-9497-4c000544106c",
- "webhook_type": "issuing_event",
- "key": "string",
- "mode": "basic",
- "origin": "default_snapshot",
- "catalogue_version": "string",
- "expression": "string",
- "basic_compatible": true,
- "definition": {
- "fields": [
- {
- "target": "string",
- "source": "string",
- "fallback": "string",
- "default": "string"
}
], - "groups": [
- {
- "target": "string",
- "items_of": "string",
- "fields": [
- {
- "target": "string",
- "source": "string",
- "fallback": "string",
- "default": "string"
}
]
}
]
}, - "version": 0,
- "created_by": "string",
- "created_at": "2019-08-24T14:15:22Z"
}
], - "available_keys": [
- "string"
]
}Shape the request body this endpoint receives for one payload key: choose fields, rename them, and fall back to another field or a default. A definition is compiled to an expression; either way the expression is compiled and evaluated against a sample input before it is stored, and only the expression is stored. Saving replaces the previous mapping, marks it custom and increments its version. Request payloads only.
| id required | string <uuid> ID of an existing webhook endpoint. |
| webhook_type required | string (WebhookEndpointType) Enum: "issuing_event" "issuing_ledger" "issuing_authorization" "issuing_three_ds" "online_txn" "online_event" "pat_event" Must be the endpoint's own webhook type. |
| key required | string The payload key - an event type, a ledger operation, pre_auth, final_auth, otp, oob_challenge or create_online_txn. Must be one the endpoint can send. |
| mode required | string (PayloadMappingMode) Enum: "basic" "advanced" Which shape a save request carries: a definition (basic) or an expression (advanced). Only the expression is stored either way; how a mapping reopens is decided by basic_compatible on the response, not by the mode it was saved in. |
required | object (PayloadMappingDefinition) A mapping described field by field. Master-v2 compiles it to the expression the adapter evaluates. |
{- "mode": "basic",
- "definition": {
- "fields": [
- {
- "target": "string",
- "source": "string",
- "fallback": "string",
- "default": "string"
}
], - "groups": [
- {
- "target": "string",
- "items_of": "string",
- "fields": [
- {
- "target": "string",
- "source": "string",
- "fallback": "string",
- "default": "string"
}
]
}
]
}
}{- "endpoint_id": "e9ce0d4f-d433-423d-9497-4c000544106c",
- "webhook_type": "issuing_event",
- "key": "string",
- "mode": "basic",
- "origin": "default_snapshot",
- "catalogue_version": "string",
- "expression": "string",
- "basic_compatible": true,
- "definition": {
- "fields": [
- {
- "target": "string",
- "source": "string",
- "fallback": "string",
- "default": "string"
}
], - "groups": [
- {
- "target": "string",
- "items_of": "string",
- "fields": [
- {
- "target": "string",
- "source": "string",
- "fallback": "string",
- "default": "string"
}
]
}
]
}, - "version": 0,
- "created_by": "string",
- "created_at": "2019-08-24T14:15:22Z"
}Reset the key to the default payload: the server writes a fresh default snapshot of the current catalogue (origin default_snapshot, version + 1). The previous expression is kept in the audit trail.
| id required | string <uuid> ID of an existing webhook endpoint. |
| webhook_type required | string (WebhookEndpointType) Enum: "issuing_event" "issuing_ledger" "issuing_authorization" "issuing_three_ds" "online_txn" "online_event" "pat_event" Must be the endpoint's own webhook type. |
| key required | string The payload key - an event type, a ledger operation, pre_auth, final_auth, otp, oob_challenge or create_online_txn. Must be one the endpoint can send. |
{- "error_code": "string",
- "message": "string",
- "details": [
- {
- "error_code": "string",
- "message": "string",
- "param": "string",
- "reason_code": "string",
- "reason": "string"
}
]
}APIs to create, update, list, and deactivate merchants/payment gateways (“partners”) that integrate with Open Fabric.
Get all Partners associated with current Tenant
| sort | string Example: sort=name,+tenant_partner_id Multiple sorting conditions |
| name | string Filter by name |
| tenant_partner_id | string Filter by Tenant Partner id |
| slug | string Filter by slug |
| country | string Filter by country |
| website_url | string Filter by website |
| category | string Filter by category |
| page | integer Current page |
| limit | integer Deprecated Number of records |
| page_size | integer Number of records |
| labels | string Example: labels=labels=qrph,nfc Filter by Labels |
{- "data": [
- {
- "id": "4fde45e1-6e4f-4039-a8de-bb316a4adeb8",
- "name": "Lazada",
- "slug": "lazada",
- "tenant_partner_id": "4fde45e1-6e4f-4039-a8de-bb316a4adeb8",
- "email": "admin@lazada.co.th"
}, - {
- "id": "9c9a3084-772b-4ef9-9b7a-46ea5d9d33a1",
- "name": "Airpay",
- "slug": "airpay",
- "tenant_partner_id": "4fde45e1-6e4f-4039-a8de-bb316a4adeb8",
- "email": "admin@airpay.com"
}, - {
- "id": "96a0c342-88b5-4fb2-98e7-f5b217f2f14b",
- "name": "Grab",
- "slug": "grab",
- "tenant_partner_id": "4fde45e1-6e4f-4039-a8de-bb316a4adeb8",
- "email": "admin@grab.com"
}
], - "metadata": {
- "page_size": 10,
- "page": 1,
- "total_pages": 1,
- "total": 3
}
}Create a Partner
| name required | string |
| tenant_partner_id required | string [ 4 .. 36 ] characters ^[a-zA-Z0-9\-_@\.]*$ |
| slug required | string [ 4 .. 30 ] characters ^[a-z0-9][a-z0-9\-]*[a-z0-9]$ |
string <email> | |
| website_url required | string <uri> |
| category | string |
| country | string |
{- "name": "string",
- "tenant_partner_id": "string",
- "slug": "string",
- "email": "user@example.com",
- "category": "string",
- "country": "string"
}{- "id": "4fde45e1-6e4f-4039-a8de-bb316a4adeb8",
- "name": "Lazada",
- "tenant_partner_id": "4fde45e1-6e4f-4039-a8de-bb316a4adeb8",
- "slug": "lazada",
}{- "id": "4fde45e1-6e4f-4039-a8de-bb316a4adeb8",
- "tenant_partner_id": "4fde45e1-6e4f-4039-a8de-bb316a4adeb8",
- "name": "Lazada",
- "slug": "lazada",
- "email": "admin@lazada.co.th"
}Update a Partner with the current Tenant
| partner_id required | string |
Body request to update Partner for Tenant
| name | string |
| website_url | string <uri> |
| category | string |
| country | string |
string <email> | |
| tenant_partner_id | string [ 4 .. 36 ] characters ^[a-zA-Z0-9\-_@\.]*$ |
{- "tenant_partner_id": "4fde45e1-6e4f-4039-a8de-bb316a4adeb8",
- "name": "Lazada",
- "email": "admin@lazada.co.th"
}{- "id": "4fde45e1-6e4f-4039-a8de-bb316a4adeb8",
- "tenant_partner_id": "4fde45e1-6e4f-4039-a8de-bb316a4adeb8",
- "name": "Lazada",
- "slug": "lazada",
- "email": "admin@lazada.co.th"
}APIs to manage partner credentials, callback subscriptions, and payment gateway credentials used for token handover.
Retrieve API credentials of a Partner
| partner_id required | string <uuid> Partner ID |
| alias required | string^[\S]+$ Alias for the credentials |
{- "alias": "default",
- "client_id": "id119i9d8ekasjc9x",
- "client_secret": "secret3jjsj3jdjk2jkesk"
}Revoke and request new API credentials of a Partner
| partner_id required | string <uuid> Partner ID |
| alias required | string^[\S]+$ Alias for the credentials |
{- "alias": "default",
- "client_id": "id119i9d8ekasjc9x",
- "client_secret": "secret3jjsj3jdjk2jkesk"
}Create a webhook subscription for a Partner
| partner_id required | string <uuid> Partner ID |
| webhook_type | string (WebhookType) Enum: "online" "pat_provision" Webhook type |
Notification subscription object to init
| config required | object Configuration options for the subscription |
| subscribed_events required | Array of strings |
{- "type": "webhook",
- "subscribed_events": [
- "*"
], - "config": {
- "authConfig": {
- "header": "X-API-Key",
- "value": "HxMrzQBFbaDeLkUar87nczWNi"
}
}
}{- "id": "cd992711-498f-47be-b636-cf2e3eaad935",
- "tenant_id": "00fcf093-71fb-4349-8c0b-de810480d6b1",
- "partner_id": "00fcf093-71fb-4349-8c0b-de810480d6b2",
- "type": "webhook",
- "subscribed_events": [
- "*"
], - "config": {
- "authConfig": {
- "header": "X-API-Key",
- "value": "HxMrzQBFbaDeLkUar87nczWNi"
}
}
}Update a webhook subscription of a Partner
| partner_id required | string <uuid> Partner ID |
| id required | string <uuid> ID of an existing notification subscription |
| webhook_type | string (WebhookType) Enum: "online" "pat_provision" Webhook type |
Notification subscription object to update
| config required | object Configuration options for the subscription |
| subscribed_events required | Array of strings |
{- "type": "webhook",
- "subscribed_events": [
- "*"
], - "config": {
- "authConfig": {
- "header": "X-API-Key",
- "value": "HxMrzQBFbaDeLkUar87nczWNi"
}
}
}{- "id": "cd992711-498f-47be-b636-cf2e3eaad935",
- "tenant_id": "00fcf093-71fb-4349-8c0b-de810480d6b1",
- "partner_id": "00fcf093-71fb-4349-8c0b-de810480d6b2",
- "type": "webhook",
- "subscribed_events": [
- "*"
], - "config": {
- "authConfig": {
- "header": "X-API-Key",
- "value": "HxMrzQBFbaDeLkUar87nczWNi"
}
}
}List all PG credentials of a Partner
| partner_id required | string <uuid> Partner ID |
| pg_name | string^[\S]+$ pg name |
{- "value": {
- "id": "143334c3-1b7d-433a-939a-f63c9022f800",
- "tenant_id": "a6dbbdab-1b7d-433a-939a-f63c9022f833",
- "partner_id": "27666828-57f9-4709-a9a9-84167e091f5f",
- "pg_name": "xendit",
- "credential_format": "api_key_pair",
- "redacted_credentials": {
- "api_key_pair": {
- "public_api_key": "aDSlnuizcvjsdl89ucIOasdzxczxczxckjzxkcjzsODMz",
- "private_api_key": "aDSlnuizcvjsdl89ucIOasdzxczxczxckjzxkcjzsODMz"
}
}, - "additional_params": {
- "processing_channel_id": "aDSlnuizcvjsdl89ucIOasdzxczxczxckjzxkcjzsODMz"
}, - "charge_config": {
- "request_pg_3ds": true,
- "headless_3ds": false
}
}
}Update a PG credential for a PG of a Partner
| partner_id required | string <uuid> Partner ID |
| pg_name required | string^[\S]+$ PG name |
| credential_format required | string (CredentialFormat) Value: "api_key_pair" |
ApiKeyPGCredential (object) (PGCredentialData) | |
object | |
object (ChargeConfig) |
{- "value": {
- "credential_format": "api_key_pair",
- "credentials": {
- "api_key_pair": {
- "public_api_key": "aDSlnuizcvjsdl89ucIOasdzxczxczxckjzxkcjzsODMz",
- "private_api_key": "aDSlnuizcvjsdl89ucIOasdzxczxczxckjzxkcjzsODMz"
}
}, - "additional_params": {
- "processing_channel_id": "aDSlnuizcvjsdl89ucIOasdzxczxczxckjzxkcjzsODMz"
}, - "charge_config": {
- "request_pg_3ds": true,
- "headless_3ds": false
}
}
}{- "id": "143334c3-1b7d-433a-939a-f63c9022f800",
- "tenant_id": "a6dbbdab-1b7d-433a-939a-f63c9022f833",
- "partner_id": "27666828-57f9-4709-a9a9-84167e091f5f",
- "pg_name": "xendit",
- "credential_format": "api_key_pair",
- "redacted_credentials": {
- "api_key_pair": {
- "public_api_key": "aDSlnuizcvjsdl89ucIOasdzxczxczxckjzxkcjzsODMz",
- "private_api_key": "aDSlnuizcvjsdl89ucIOasdzxczxczxckjzxkcjzsODMz"
}
}, - "additional_params": {
- "processing_channel_id": "aDSlnuizcvjsdl89ucIOasdzxczxczxckjzxkcjzsODMz"
}, - "charge_config": {
- "request_pg_3ds": true,
- "headless_3ds": false
}
}Get a PG credential for a PG of Partner
| partner_id required | string <uuid> Partner ID |
| pg_name required | string^[\S]+$ PG name |
{- "id": "143334c3-1b7d-433a-939a-f63c9022f800",
- "tenant_id": "a6dbbdab-1b7d-433a-939a-f63c9022f833",
- "partner_id": "27666828-57f9-4709-a9a9-84167e091f5f",
- "pg_name": "xendit",
- "credential_format": "api_key_pair",
- "redacted_credentials": {
- "api_key_pair": {
- "public_api_key": "aDSlnuizcvjsdl89ucIOasdzxczxczxckjzxkcjzsODMz",
- "private_api_key": "aDSlnuizcvjsdl89ucIOasdzxczxczxckjzxkcjzsODMz"
}
}, - "additional_params": {
- "processing_channel_id": "aDSlnuizcvjsdl89ucIOasdzxczxczxckjzxkcjzsODMz"
}, - "charge_config": {
- "request_pg_3ds": true,
- "headless_3ds": false
}
}Delete credentials for a PG of a Partner
| partner_id required | string <uuid> Partner ID |
| pg_name required | string^[\S]+$ PG name |
{- "error_code": "string",
- "message": "string",
- "details": [
- {
- "error_code": "string",
- "message": "string",
- "param": "string",
- "reason_code": "string",
- "reason": "string"
}
]
}APIs that merchants and payment gateways use with the Open Fabric Merchant SDK to create and manage transactions.
This will be called by Partner to initialize a transaction before interacting with payment methods
| txn_trace_id | string <uuid> Trace UUID (v4) to follow payment sessions |
| Idempotency-Key | string Unique value submitted by the client to ensure idempotent request when creating transaction. |
Transaction object to init
| instrument | string Default: "web_checkout" Instrument of the transaction request. Can be omitted for the |
| tenant_id | string <uuid> OpenFabric Generated ID for the Tenant of the payment method, only for backward-compatibility. If not provided, it will use the ID of the Tenant linked with Partner. |
| partner_redirect_success_url required | string <uri> Redirect URL Configured by Partner - when transaction is approved by Tenant |
| partner_redirect_fail_url required | string <uri> Redirect URL Configured by Partner - when transaction is denied by Tenant |
| partner_reference_id required | string^[a-zA-Z0-9\-_@\.]*$ Transaction ID set by Partner and sent to OpenFabric |
required | object (CustomerInfo) OpenFabric collects the below customer Info Collection from merchants. We will pass-through the collected info to Tenant |
| amount required | number >= 0.01 Transaction amount for which Tenant's authorization is requested |
| currency required | string = 3 characters ^[A-Z]*$ Transaction Currency for which Tenant's authorization is requested (ISO 4217 Alpha-3 currency codes) |
required | object (TransactionDetails) Transaction Details sent by Partner. |
| pg_name | string Payment Gateway name |
| pg_publishable_key | string Payment Gateway's publishable_key |
| pg_flow | string (PGFlow) Enum: "tokenization" "charge" for which flow that Partner would like OF to execute. If it is not set, default to Tokenization |
| pg_additional_params | object Additional parameters required in the card tokenization/charge request for the given Payment Gateway |
{- "partner_reference_id": "P1293201980299030",
- "tenant_id": "00fcf093-71fb-4349-8c0b-de810480d6b1",
- "partner_redirect_success_url": "https://sample-merchant-flow.dev.openfabric.co?id=f0398e5-d045-441f-b130-bcd517964775&state=PAID",
- "partner_redirect_fail_url": "https://sample-merchant-flow.dev.openfabric.co?id=f0398e5-d045-441f-b130-bcd517964775&state=CANCELLED",
- "customer_info": {
- "mobile_number": "+6587654321",
- "first_name": "BNPL",
- "last_name": "Developer",
- "email": "developer@bnpl1.com",
- "partner_reference_id": "cd992711-498f-47be-b636-cf2e3eaad935"
}, - "amount": 120.1,
- "currency": "SGD",
- "transaction_details": {
- "shipping_address": {
- "country": "Singapore",
- "country_code": "SG",
- "address_line_1": "80 Robinson Road",
- "address_line_2": "#09-01",
- "address_line_3": "#09-01",
- "post_code": "068898"
}, - "billing_address": {
- "country": "Singapore",
- "country_code": "SG",
- "address_line_1": "80 Robinson Road",
- "address_line_2": "#09-01",
- "address_line_3": "#09-01",
- "post_code": "068898"
}, - "items": [
- {
- "item_id": "P100",
- "name": "iPhone",
- "price": 11020,
- "quantity": 1,
- "variation_name": "Black, 128GB",
- "original_price": 12020,
- "categories": [
- "Electronics"
]
}, - {
- "item_id": "P101",
- "name": "iPhone SE case",
- "price": 1000,
- "quantity": 1,
- "variation_name": "White",
- "categories": [
- "Accessories"
]
}
], - "tax_amount": 390.6,
- "shipping_amount": 1020,
- "original_amount": 13020
}
}{- "id": "ff0398e5-d045-441f-b130-bcd517964775",
- "partner_reference_id": "P1293201980299030",
- "tenant_reference_id": "Tenant-cd992711-498f-47be-b636-cf2e3eaad935",
- "tenant_id": "00fcf093-71fb-4349-8c0b-de810480d6b1",
- "partner_id": "9bde4fbf-893b-49f9-b7b3-4079a76bb362",
- "tenant_partner_id": "27666828-57f9-4709-a9a9-84167e091f5f",
- "partner_redirect_success_url": "https://sample-merchant-flow.dev.openfabric.co??id=f0398e5-d045-441f-b130-bcd517964775&state=PAID",
- "partner_redirect_fail_url": "https://sample-merchant-flow.dev.openfabric.co?id=f0398e5-d045-441f-b130-bcd517964775&state=CANCELLED",
- "customer_id": "88db7aa7-2cdd-42cc-9827-8d46f936ef79",
- "customer_info": {
- "mobile_number": "+6587654321",
- "first_name": "postpebnpl",
- "last_name": "developer",
- "country": "Singapore",
- "country_code": "SG",
- "email": "developer@bnpl1.com"
}, - "amount": 120.1,
- "currency": "SGD",
- "status": "in_progress",
- "created_at": "2021-11-06T04:26:47.450Z",
- "updated_at": "2021-11-06T04:26:47.450Z"
}This will return Detailed Transaction by Open Fabric Reference ID
| id required | string <uuid> |
| txn_trace_id | string <uuid> Trace UUID (v4) to follow payment sessions |
{- "value": {
- "id": "ff0398e5-d045-441f-b130-bcd517964775",
- "partner_reference_id": "P1293201980299030",
- "tenant_reference_id": "Tenant-cd992711-498f-47be-b636-cf2e3eaad935",
- "tenant_id": "00fcf093-71fb-4349-8c0b-de810480d6b1",
- "partner_id": "9bde4fbf-893b-49f9-b7b3-4079a76bb362",
- "tenant_partner_id": "27666828-57f9-4709-a9a9-84167e091f5f",
- "partner_redirect_success_url": "https://sample-merchant-flow.dev.openfabric.co??id=f0398e5-d045-441f-b130-bcd517964775&state=PAID",
- "partner_redirect_fail_url": "https://sample-merchant-flow.dev.openfabric.co?id=f0398e5-d045-441f-b130-bcd517964775&state=CANCELLED",
- "customer_id": "88db7aa7-2cdd-42cc-9827-8d46f936ef79",
- "customer_info": {
- "mobile_number": "+6587654321",
- "first_name": "postpebnpl",
- "last_name": "developer",
- "country": "Singapore",
- "country_code": "SG",
- "email": "developer@bnpl1.com"
}, - "amount": 120.1,
- "currency": "SGD",
- "status": "in_progress",
- "created_at": "2021-11-06T04:26:47.450Z",
- "updated_at": "2021-11-06T04:26:47.450Z"
}
}This will refund a transaction that was charged by Open Fabric on behalf of Partner
| id required | string <uuid> |
| Idempotency-Key | string Unique value submitted by the partner to ensure idempotent request when refunding transaction. |
Refund request body
| amount required | number >= 0.001 Refund amount |
| additional_properties | object |
| reason | string |
{- "amount": 10.1,
- "reason": "Out of goods"
}{- "value": {
- "id": "00fcf093-71fb-4349-8c0b-de810480d6b1",
- "pg_refund_id": "00fcfasfas24r234saf",
- "data": {
- "id": "00fcfasfas24r234saf",
- "external_id": "00fcf0sf-71fb-4349-8c0b-213412349840"
}
}
}This will fetch the transaction by partner reference id
| partner_reference_id required | string |
{- "value": {
- "id": "ff0398e5-d045-441f-b130-bcd517964775",
- "partner_reference_id": "P1293201980299030",
- "tenant_reference_id": "Tenant-cd992711-498f-47be-b636-cf2e3eaad935",
- "tenant_id": "00fcf093-71fb-4349-8c0b-de810480d6b1",
- "partner_id": "9bde4fbf-893b-49f9-b7b3-4079a76bb362",
- "tenant_partner_id": "27666828-57f9-4709-a9a9-84167e091f5f",
- "partner_redirect_success_url": "https://sample-merchant-flow.dev.openfabric.co??id=f0398e5-d045-441f-b130-bcd517964775&state=PAID",
- "partner_redirect_fail_url": "https://sample-merchant-flow.dev.openfabric.co?id=f0398e5-d045-441f-b130-bcd517964775&state=CANCELLED",
- "customer_id": "88db7aa7-2cdd-42cc-9827-8d46f936ef79",
- "customer_info": {
- "mobile_number": "+6587654321",
- "first_name": "postpebnpl",
- "last_name": "developer",
- "country": "Singapore",
- "country_code": "SG",
- "email": "developer@bnpl1.com"
}, - "amount": 120.1,
- "currency": "SGD",
- "status": "in_progress",
- "created_at": "2021-11-06T04:26:47.450Z",
- "updated_at": "2021-11-06T04:26:47.450Z"
}
}With the payment methods input, we identify Partner by access_token, only payment methods available with this Partner will be returned
| txn_trace_id | string <uuid> Trace UUID (v4) to follow payment sessions |
{- "value": [
- {
- "tenant_id": "00fcf093-71fb-4349-8c0b-de810480d6b1",
- "name": "Sample BNPL",
- "slug": "sample-bnpl",
- "tenant_partner_id": "27666828-57f9-4709-a9a9-84167e091f5f"
}
]
}Notification sent to your partner's backend when a transaction is approved.
| txn_id required | string <uuid> OpenFabric Transaction ID |
| txn_ref_id required | string <uuid> Transaction reference ID. Internally it is the equivalent of |
| txn_state required | string (MerchantTransactionStatus) Enum: "in_progress" "approved" "failed" "reversed" Transaction status for Partner |
| txn_amt required | number Transaction amount |
| txn_ccy required | string Transaction currency |
| txn_app_amt required | number Transaction approved amount |
| txn_app_ccy required | string Transaction approved currency |
| txn_created_at required | string <date-time> |
| txn_updated_at required | string <date-time> |
| txn_tenant_id | string |
| txn_card_token | string Short-lived token to access the VCN details generated for the
transaction. Internally it is the equivalent of |
| txn_pg | string Payment gateway name. Used for PG integrated flow |
| txn_pg_token | string Payment gateway token. Used for PG integrated flow |
| txn_pg_charge_id | string id of the charge transaction sent back from pg |
| txn_pg_response | object |
{- "txn_id": "ff0398e5-d045-441f-b130-bcd517964775",
- "txn_ref_id": "P1293201980299030",
- "txn_state": "approved",
- "txn_amt": 120.1,
- "txn_ccy": "SGD",
- "txn_app_amt": 120.1,
- "txn_app_ccy": "SGD",
- "txn_created_at": "2021-11-06T04:26:47.450Z",
- "txn_updated_at": "2021-11-06T04:26:47.450Z",
- "txn_pg": "stripe",
- "txn_pg_token": "YTZkYmJkYWItMWI3ZC00MzNhLTkzOWEtZjYzYzkwMjJmODMz"
}Notification sent to your partner's backend when a transaction is failed.
| txn_id required | string <uuid> OpenFabric Transaction ID |
| txn_ref_id required | string <uuid> Transaction reference ID. Internally it is the equivalent of |
| txn_state required | string (MerchantTransactionStatus) Enum: "in_progress" "approved" "failed" "reversed" Transaction status for Partner |
| txn_created_at required | string <date-time> |
| txn_updated_at required | string <date-time> |
| txn_tenant_id | string |
| txn_reason | string Reason to decline the transaction, submitted by Tenant. |
{- "txn_id": "ff0398e5-d045-441f-b130-bcd517964775",
- "txn_ref_id": "P1293201980299030",
- "txn_state": "failed",
- "txn_created_at": "2021-11-06T04:26:47.450Z",
- "txn_updated_at": "2021-11-06T04:26:47.450Z",
- "txn_reason": "Insufficient amount"
}APIs that merchants and payment gateways use to manage their integration settings.
Update webhook subscription and PG credentials settings of a Partner
Webhook and PG credentials details request for Partner
object (AccountNotificationSubscriptionRequest) | |
object |
{- "value": {
- "webhook": {
- "type": "webhook",
- "subscribed_events": [
- "*"
], - "config": {
- "authConfig": {
- "header": "X-API-Key",
- "value": "HxMrzQBFbaDeLkUar87nczWNi"
}
}
}, - "payment_gateway": {
- "pg_name": "xendit",
- "credential_format": "api_key_pair",
- "credentials": {
- "api_key_pair": {
- "public_api_key": "pk-rdjftkyghjl9876543210",
- "private_api_key": "sk-rdjftkyghjl9876543210"
}
}
}
}
}{- "webhook": {
- "id": "cd992711-498f-47be-b636-cf2e3eaad935",
- "tenant_id": "00fcf093-71fb-4349-8c0b-de810480d6b1",
- "partner_id": "00fcf093-71fb-4349-8c0b-de810480d6b2",
- "type": "webhook",
- "subscribed_events": [
- "*"
], - "config": {
- "authConfig": {
- "header": "X-API-Key",
- "value": "HxMrzQBFbaDeLkUar87nczWNi"
}
}
}, - "payment_gateway": {
- "id": "143334c3-1b7d-433a-939a-f63c9022f800",
- "tenant_id": "00fcf093-71fb-4349-8c0b-de810480d6b1",
- "partner_id": "00fcf093-71fb-4349-8c0b-de810480d6b2",
- "pg_name": "xendit",
- "credential_format": "api_key_pair",
- "redacted_credentials": {
- "api_key_pair": {
- "public_api_key": "aDSlnuizcvjsdl89ucIOasdzxczxczxckjzxkcjzsODMz",
- "private_api_key": "aDSlnuizcvjsdl89ucIOasdzxczxczxckjzxkcjzsODMz"
}
}
}
}APIs your backend uses for In-App Shopping: create a shopping session with a single-use exchange token, then create and approve the transaction after your customer confirms the order.
See In-App Shopping for the end-to-end integration guide.
Called by your backend (server-to-server) with its OAuth access
token. Inserts a pending session row and mints a single-use exchange
token (TTL 60s) that your backend forwards via your app to
the Mobile SDK.
| domain required | string [ 1 .. 500 ] characters Merchant domain with optional locale path. Both nike.com/sg and nike.com/jp are distinct merchants. |
| tenant_user_ref | string <= 255 characters Your reference for the shopping user (audit only). |
{- "domain": "nike.com/sg",
- "tenant_user_ref": "string"
}{- "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",
- "exchange_token": "string",
- "expires_at": "2019-08-24T14:15:22Z",
- "merchant": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "domain": "string",
- "name": "string",
- "status": "active",
- "automation": {
- "checkout_detection": {
- "urls": [
- "string"
], - "ready": [
- {
- "selector": "string",
- "state": "string",
- "value": "string",
- "url_pattern": "string",
- "frame_url": "string",
- "frame_selector": "string"
}
]
}, - "payment_status_detection": {
- "timeout_ms": 0,
- "outcomes": [
- {
- "status": "succeeded",
- "urls": [
- "string"
], - "ready": [
- {
- "selector": "string",
- "state": "string",
- "value": "string",
- "url_pattern": "string",
- "frame_url": "string",
- "frame_selector": "string"
}
]
}
]
}, - "order_extractors": [
- {
- "url_pattern": "string",
- "selectors": {
- "property1": "string",
- "property2": "string"
}
}
], - "payment_flows": [
- {
- "flow_id": "string",
- "url_pattern": "string",
- "payment_method": "card",
- "steps": [
- {
- "action": "click",
- "selector": "string",
- "frame_url": "string",
- "frame_selector": "string",
- "field_name": "card_number",
- "format": "YY",
- "ms": 0,
- "timeout_ms": 0,
- "url_pattern": "string",
- "state": "string",
- "value": "string",
- "condition": {
- "skip_if_visible": "string",
- "frame_url": "string",
- "frame_selector": "string"
}, - "message": "string"
}
], - "pre_hook": [
- {
- "action": "click",
- "selector": "string",
- "frame_url": "string",
- "frame_selector": "string",
- "field_name": "card_number",
- "format": "YY",
- "ms": 0,
- "timeout_ms": 0,
- "url_pattern": "string",
- "state": "string",
- "value": "string",
- "condition": {
- "skip_if_visible": "string",
- "frame_url": "string",
- "frame_selector": "string"
}, - "message": "string"
}
]
}
]
}, - "health": {
- "total_sessions": 0,
- "automation_success_rate": 1,
- "last_failure_at": "2019-08-24T14:15:22Z",
- "status": "healthy"
}
}
}Create a transaction originated from your side. The lifecycle depends on the instrument value:
most instruments initiate a transaction context that you approve in a second step; in_app_shopping
creates and approves the transaction in a single atomic call and mints the VCN immediately.
| Idempotency-Key | string Unique value submitted by the client to ensure idempotent request when creating transaction. |
| tenant_reference_id required | string >= 4 characters ^[a-zA-Z0-9\-_@\.]*$ Transaction ID in Tenant system. |
| amount required | number Transaction amount for which Tenant's authorization is requested |
| currency required | string = 3 characters ^[A-Z]*$ Transaction Currency for which Tenant's authorization is requested (ISO 4217 Alpha-3 currency codes) |
| instrument required | string (RoutingDataInitializingInstrument) Enum: "web_checkout" "unilateral_checkout" "one_click_checkout" "recurring" "tenant_recurring" "pba_static_token" "qrph" "sgqr" "vietqr" "tap_and_pay" "manual_card_entry" "google_pay" "samsung_pay" "apple_pay" "in_app_shopping" Instrument used to initialize the transaction |
| qr_code | string String value obtained by scanning a Payment QR code containing transaction details |
| tenant_customer_ref | string Tenant's customer reference ID |
| tenant_link_ref | string Tenant's link reference ID |
| tenant_partner_ref | string Tenant's partner reference ID |
| session_id | string <uuid> In-App Shopping session ID. Required when instrument is 'in_app_shopping'. |
{- "tenant_reference_id": "Tenant-cd992711-498f-47be-b636-cf2e3eaad935",
- "amount": 120.1,
- "currency": "SGD",
- "instrument": "qrph",
- "qr_code": "00020101021128620011ph.ppmi.p2m0111GXCHPHM2XXX032121702000005469871609905030005204581453036085802PH5917S and R MBTC 91826006Taguig6104163062650012ph.ppmi.qrph0308SRSU002005212170500000669901340940708GEN0035163049EE7"
}{- "id": "ff0398e5-d045-441f-b130-bcd517964775",
- "partner_reference_id": "P1293201980299030",
- "tenant_reference_id": "cd992711-498f-47be-b636-cf2e3eaad935",
- "tenant_partner_id": "27666828-57f9-4709-a9a9-84167e091f5f",
- "tenant_id": "00fcf093-71fb-4349-8c0b-de810480d6b1",
- "partner_id": "9bde4fbf-893b-49f9-b7b3-4079a76bb362",
- "partner_name": "Lazada",
- "customer_id": "88db7aa7-2cdd-42cc-9827-8d46f936ef79",
- "partner_redirect_success_url": "http://sample-merchant-flow.openfabric.co?id=f0398e5-d045-441f-b130-bcd517964775&state=PAID",
- "partner_redirect_fail_url": "http://sample-merchant-flow.openfabric.co?id=f0398e5-d045-441f-b130-bcd517964775&state=CANCELLED",
- "gateway_success_url": "http://of-gateway.s3-website-ap-southeast-1.amazonaws.com?reference_id=P1293201980299030&state=PAID",
- "customer_info": {
- "mobile_number": "+6587654321",
- "first_name": "postpebnpl",
- "last_name": "developer",
- "country": "Singapore",
- "country_code": "SG",
- "email": "developer@bnpl1.com"
}, - "amount": 120.1,
- "currency": "SGD",
- "status": "created",
- "card_reference_id": "7743087",
- "created_at": "2021-11-06T04:26:47.450Z",
- "updated_at": "2021-11-06T04:26:47.450Z"
}APIs your core ledger calls on Expense Management: an authorization check before you approve a card or QR payment, and account events that report what happened on businesses' funding accounts.
See Expense Management integration for more details.
Checks a card or QR payment against the business's expense policy before you approve it. Expense Management advises; you decide, hold and post.
Answer within 1 second; on a timeout, 5xx or 429, apply your own stand-in decision. Idempotent on check_id.
Authenticate with an Open Fabric access token that has the exp.bank scope.
See Authorization checks for more details.
| check_id required | string <= 128 characters Your ID for this check. A repeat returns the stored decision. |
| kind required | string Enum: "card" "qr" |
| stage required | string Enum: "pre_auth" "final_auth" "incremental" "qr_payment"
|
| related_check_id | string or null For |
| account_ref required | string <= 64 characters The business's funding account in your ledger. |
required | object The amount to check, in the account's currency. For |
ExpenseMoney (object) or null The amount in the transaction's currency, when it differs from the account's. Else null. For | |
required | object (ExpensePayer) Who is paying. For a card payment, send |
ExpenseMerchant (object) or null | |
ExpenseCardPaymentDetails (object) or null Required when | |
ExpenseQrCheckDetails (object) or null Required when | |
| requested_at required | string <date-time> |
{- "check_id": "CHK-20261104-000123",
- "kind": "card",
- "stage": "pre_auth",
- "related_check_id": null,
- "account_ref": "acc_7f3e",
- "amount": {
- "amount": "280.00",
- "currency": "SGD"
}, - "original_amount": null,
- "payer": {
- "business_ref": "biz_01jbty0z0tfcz9mg0x5gxmmqv2",
- "card_ref": "card_01jbty0z0tfcz9mg0x5gxmmqv4",
- "bank_account_ref": null
}, - "merchant": {
- "name": "Marina Bay Hotel",
- "mcc": "7011",
- "country": "SG",
- "city": "Singapore",
- "merchant_id": null
}, - "card": {
- "of_transaction_id": "9f1c2d3e-4b5a-6789-8abc-def012345678",
- "of_static_token_id": null,
- "network": "visa",
- "entry_mode": "ecommerce",
- "policy_result": null
}, - "qr": null,
- "requested_at": "2026-11-04T09:15:00Z"
}{- "check_id": "CHK-20261104-000123",
- "decision": "decline",
- "reason_code": "merchant_category_blocked",
- "appealable": true,
- "decided_at": "2026-11-04T09:15:00.120Z"
}Reports what happened on businesses' funding accounts: holds, debits, credits, payouts, fees and declines. Send 1 to 100 events per call, at least once and in any order.
Each event is idempotent on event_id and gets its own result. Retry the whole batch on a 5xx or a timeout; never retry an event that is rejected.
Authenticate with an Open Fabric access token that has the exp.bank scope.
See Account events for more details.
required | Array of objects (ExpenseAccountEvent) [ 1 .. 100 ] items | ||||||||||||||
Array ([ 1 .. 100 ] items)
| |||||||||||||||
{- "events": [
- {
- "event_id": "EVT-000981",
- "account_ref": "acc_7f3e",
- "sequence": 981,
- "occurred_at": "2026-11-04T09:15:01Z",
- "entry": {
- "entry_id": "PST-000981",
- "type": "hold",
- "amount": {
- "amount": "280.00",
- "currency": "SGD"
}, - "hold_ref": "HLD-000981",
- "value_date": null
}, - "transaction": {
- "kind": "card",
- "ref": "TXN-778812",
- "status": "authorized",
- "expense_mgmt_ref": null,
- "check_id": "CHK-20261104-000123",
- "payer": {
- "business_ref": "biz_01jbty0z0tfcz9mg0x5gxmmqv2",
- "card_ref": "card_01jbty0z0tfcz9mg0x5gxmmqv4",
- "bank_account_ref": null
}, - "merchant": {
- "name": "Marina Bay Hotel",
- "mcc": "7011",
- "country": "SG",
- "city": "Singapore",
- "merchant_id": null
}, - "card": {
- "of_transaction_id": "9f1c2d3e-4b5a-6789-8abc-def012345678",
- "of_static_token_id": null,
- "last4": "4242",
- "authorization_code": "A1B2C3",
- "network": "visa",
- "policy_result": null
}
}, - "balance": {
- "available": {
- "amount": "49720.00",
- "currency": "SGD"
}, - "current": {
- "amount": "50000.00",
- "currency": "SGD"
}
}
}
]
}{- "results": [
- {
- "event_id": "EVT-000981",
- "status": "applied",
- "code": null
}
]
}APIs your core ledger hosts for Expense Management: account lookup, QR payments and payouts. Results come back as account events, not callbacks.
See Core ledger APIs for more details.
Returns a funding account with its holder, masked number and live balance. Called when a funding account is linked to a business and to show balances.
See Core ledger APIs for more details.
| account_ref required | string <= 64 characters Example: acc_7f3e Your account identifier. |
{- "account_ref": "acc_7f3e",
- "holder_name": "Acme Trading Pte. Ltd.",
- "account_mask": "••••1234",
- "currency": "SGD",
- "available": {
- "amount": "49720.00",
- "currency": "SGD"
}, - "current": {
- "amount": "50000.00",
- "currency": "SGD"
}, - "as_of": "2026-11-04T09:15:00Z",
- "last_sequence": 980
}Optional. Returns an account's events after a sequence, oldest first, in the same shape you post to Send account events. Called to fill a gap in the event sequence.
Answer 404 if you don't offer it.
| account_ref required | string <= 64 characters Example: acc_7f3e Your account identifier. |
| after_sequence | integer >= 0 Example: after_sequence=980 Only events with a greater |
| limit | integer [ 1 .. 500 ] Default: 100 Page size. |
{- "data": [
- {
- "event_id": "string",
- "account_ref": "string",
- "sequence": 0,
- "occurred_at": "2019-08-24T14:15:22Z",
- "entry": {
- "entry_id": "string",
- "type": "hold",
- "amount": {
- "amount": "280.00",
- "currency": "SGD"
}, - "hold_ref": "string",
- "value_date": "2019-08-24"
}, - "transaction": {
- "kind": "card",
- "ref": "string",
- "status": "pending",
- "expense_mgmt_ref": "string",
- "check_id": "string",
- "payer": {
- "business_ref": "biz_01jbty0z0tfcz9mg0x5gxmmqv2",
- "card_ref": "card_01jbty0z0tfcz9mg0x5gxmmqv4",
- "bank_account_ref": null
}, - "amount": {
- "amount": "280.00",
- "currency": "SGD"
}, - "original_amount": {
- "amount": "280.00",
- "currency": "SGD"
}, - "merchant": {
- "name": "Marina Bay Hotel",
- "mcc": "7011",
- "country": "SG",
- "city": "Singapore",
- "merchant_id": null
}, - "card": {
- "of_transaction_id": "9f1c2d3e-4b5a-6789-8abc-def012345678",
- "of_static_token_id": null,
- "network": "visa",
- "entry_mode": "ecommerce",
- "policy_result": null,
- "last4": "string",
- "authorization_code": "string"
}, - "qr": {
- "standard": "string",
- "payment_ref": "string",
- "merchant_account_name": "string"
}, - "counterparty": {
- "name": "string",
- "account_masked": "string"
}, - "decline": {
- "code": "string",
- "source": "bank",
- "message": "string"
}
}, - "balance": {
- "available": {
- "amount": "280.00",
- "currency": "SGD"
}, - "current": {
- "amount": "280.00",
- "currency": "SGD"
}
}
}
], - "has_more": true
}Pays a merchant from the business's funding account, for a QR payment started in the Expense Management app. The policy is already checked.
Idempotent on payment_ref: pay at most once per reference. Post the final result as an account event with transaction.expense_mgmt_ref set to payment_ref.
| payment_ref required | string Expense Management's QR payment ID ( |
required | object |
required | object The merchant, as read from the QR code. |
required | object (ExpenseMoney) An amount as a decimal string with its ISO 4217 currency code. |
required | object |
{- "payment_ref": "qrp_01jbty0z0tfcz9mg0x5gxmmqv5",
- "debtor": {
- "account_ref": "0123456789"
}, - "creditor": {
- "name": "Marina Bay Hotel",
- "city": "Singapore",
- "country": "SG",
- "mcc": "7011",
- "merchant_account": "SG.PAYNOW:201234567R",
- "acquirer_id": null
}, - "amount": {
- "amount": "60.00",
- "currency": "SGD"
}, - "qr": {
- "standard": "sgqr",
- "payload": "00020101021226370009SG.PAYNOW010120210201234567R5204701153037025406"
}
}{- "payment_ref": "qrp_01jbty0z0tfcz9mg0x5gxmmqv5",
- "issuer_payment_ref": "ISS-998",
- "status": "accepted",
- "amount": {
- "amount": "60.00",
- "currency": "SGD"
}, - "rejection_code": null,
- "created_at": "2026-11-02T09:16:00Z",
- "completed_at": null
}Returns a QR payment by Expense Management's payment_ref. Answer 404 only for a payment you never received: Expense Management then submits it again.
| payment_ref required | string Example: qrp_01jbty0z0tfcz9mg0x5gxmmqv5 Expense Management's QR payment ID. |
{- "payment_ref": "qrp_01jbty0z0tfcz9mg0x5gxmmqv5",
- "issuer_payment_ref": "ISS-998",
- "status": "accepted",
- "amount": {
- "amount": "60.00",
- "currency": "SGD"
}, - "rejection_code": null,
- "created_at": "2026-11-02T09:16:00Z",
- "completed_at": null
}Pays a reimbursement or supplier from the business's funding account. Sent with an Idempotency-Key header and idempotent on reference.
Post status changes as account events with transaction.kind payout and transaction.expense_mgmt_ref set to reference.
| Idempotency-Key required | string Unique key for this payout request. |
| reference required | string Expense Management's payment ID ( |
| account_ref required | string <= 64 characters The funding account to pay from. |
required | object |
required | object (ExpenseMoney) An amount as a decimal string with its ISO 4217 currency code. |
{- "reference": "pay_01jbzr7kq0f8rt5mx2vw3c4d5e",
- "account_ref": "acc_7f3e",
- "beneficiary": {
- "account_name": "Rachel Tan",
- "account_number": "0001234506789",
- "bank_code": "BNKASGSG"
}, - "amount": {
- "amount": "35.00",
- "currency": "SGD"
}
}{- "payout_ref": "PO-000123",
- "reference": "pay_01jbzr7kq0f8rt5mx2vw3c4d5e",
- "account_ref": "acc_7f3e",
- "beneficiary_account_masked": "••••6789",
- "amount": {
- "amount": "35.00",
- "currency": "SGD"
}, - "status": "pending",
- "failure_reason": null,
- "updated_at": "2026-11-05T01:00:00Z"
}Returns a payout by Expense Management's reference. Answer 404 only for a payout you never received.
| payout_ref required | string Example: pay_01jbzr7kq0f8rt5mx2vw3c4d5e Expense Management's payment ID, as sent in |
{- "payout_ref": "PO-000123",
- "reference": "pay_01jbzr7kq0f8rt5mx2vw3c4d5e",
- "account_ref": "acc_7f3e",
- "beneficiary_account_masked": "••••6789",
- "amount": {
- "amount": "35.00",
- "currency": "SGD"
}, - "status": "pending",
- "failure_reason": null,
- "updated_at": "2026-11-05T01:00:00Z"
}Notification sent from our platform to your backend when an invoice is published, with a link to
a zip of the invoice PDF and its usage reports, plus the API to generate a fresh download URL once
the one in the notification expires. Subscribe a webhook endpoint to
v1:billing:invoice:published to receive the notification.
Notification sent when an invoice is published, with a link to a zip of the invoice PDF and its usage reports.
Subscribe a webhook endpoint to v1:billing:invoice:published to receive it.
| notification_id required | string <uuid> The unique identifier for the notification |
| type required | string Value: "v1:billing:invoice:published" |
| created_at required | string <date-time> The creation timestamp of the notification in ISO 8601 format |
required | object (InvoicePublishedNotification) v1:billing:invoice:published |
{- "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
- "type": "v1:billing:invoice:published",
- "created_at": "2019-08-24T14:15:22Z",
- "data": {
- "notification_id": "0f8f3c5e-6a4b-4d9e-9a3e-2d7b1c6e8f10",
- "tenant_id": "7c1e4a52-0d3b-4f8e-9a61-2b5c8e7d4f10",
- "tenant_name": "acme-pay",
- "invoice_number": "INV-202617",
- "issued_at": "2026-10-10",
- "period_start": "2026-09-01T00:00:00Z",
- "period_end": "2026-10-01T00:00:00Z",
- "file_name": "INV-202617.zip",
- "file_ref": "s3://prod-reporting-exports/invoices/7c1e4a52-0d3b-4f8e-9a61-2b5c8e7d4f10/2026-10-10/INV-202617/INV-202617.zip",
- "file_checksum": "9e107d9d372bb6826bd81d3542a419d6",
- "number_of_files": 4,
- "download_url_expires_at": "2026-10-10T04:12:45Z"
}
}Generate a new time-limited download URL for an invoice's zip (the invoice PDF and all its usage reports), or for the invoice PDF or a single usage report on its own.
Use this API to regenerate the download_url received in the invoice published notification after it has expired. Pass the file_name received in the notification.
| invoice_number required | string Example: INV-202617 Invoice number |
| file_name required | string Name of the file to download, as received in the invoice published notification or returned in the invoice's |
{- "file_name": "INV-202617.zip"
}{- "filename": "INV-202617_pba_static_tokens.total_active_count.csv",
- "expires_at": "2026-10-20T08:15:00Z"
}