Skip to main content
API docs by Redocly

Open Fabric APIs (v1)

Download OpenAPI specification:Download

Open Fabric API: api@openfabric.co URL: https://openfabric.co

Open Fabric APIs, v1

Authentication

Our APIs use an authentication scheme based on OAuth 2.0. See Authentication for more details.

Request access token

Request Body schema: application/x-www-form-urlencoded
grant_type
required
string
Value: "client_credentials"
scope
string

Requested scopes for this access token, separated by whitespace. If not provided, all available scopes of the client will be requested. For the list of available scopes, please refer to the API Access Scopes document.

Responses

Request samples

Content type
application/x-www-form-urlencoded
grant_type=client_credentials&scope=resources%2Ftransactions.create%20resources%2Ftransactions.read

Response samples

Content type
application/json
{
  • "access_token": "eyJz9sdfsdfsdfsd",
  • "id_token": "dmcxd329ujdmkemkd349r",
  • "token_type": "Bearer",
  • "expires_in": 3600
}

Provision Account

API used to provision new accounts. See Provision account for more details.

Provision a new account

This API can be used to provision a new account or virtual card.

See Own App Tokens, Digital Wallet Tokens or Virtual Cards for more details.

header Parameters
Idempotency-Key
string

Unique value submitted by the partner to ensure idempotent request during provisioning.

Request Body schema: application/json
required
type
string (PbaProvisionType)
Enum: "nfc_device_token" "static_token" "push_provision"
payment_network
string (PbaPaymentNetwork)
Enum: "mastercard" "visa"
tenant_customer_ref
required
string
tenant_account_ref
required
string <= 64 characters
tenant_token_ref
string
wallet_id
string
device_name
string
tenant_account_device_ref
string <= 32 characters
billing_currency
string = 3 characters ^[A-Z]*$
object (Address)
instrument
string (PbaProvisionInstrument)
Enum: "manual_card_entry" "google_pay" "samsung_pay"
card_name
string

Name of the card

Responses

Request samples

Content type
application/json
{
  • "type": "nfc_device_token",
  • "payment_network": "mastercard",
  • "tenant_customer_ref": "string",
  • "tenant_account_ref": "string",
  • "tenant_token_ref": "string",
  • "wallet_id": "string",
  • "device_name": "string",
  • "tenant_account_device_ref": "string",
  • "billing_currency": "str",
  • "billing_address": {
    },
  • "instrument": "manual_card_entry",
  • "card_name": "string"
}

Response samples

Content type
application/json
{
  • "tenant_account_ref": "string",
  • "tenant_customer_ref": "string",
  • "tenant_account_device_ref": "string",
  • "tenant_token_ref": "string",
  • "sdk_tokenize_account_device_data": "string",
  • "of_customer_id": "9fc66daf-0a70-4712-85e0-97ae74b12eab",
  • "of_account_id": "abd67f67-aa44-4da9-a9b4-a1ddc1235bfe",
  • "of_device_id": "e29148d0-3faf-487e-b249-963965333fbe",
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
  • "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
  • "static_token_id": "3fb159c5-3595-473f-a882-31eae6265673",
  • "digital_token_id": "string",
  • "instrument": "manual_card_entry",
  • "locked": true,
  • "status": "string",
  • "provision_token": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Provision an account for an existing card

This API can be used to provision an account for an existing card.

See Own App Tokens - Tokenize an existing card for more details.

Request Body schema: application/json
required
digital_wallet
required
string (DigitalWallet)
Enum: "issuer" "google_pay" "apple_pay" "samsung_pay"
tenant_customer_ref
required
string
issuer_card_id
required
string
wallet_id
required
string
issuer_authentication_data
string
encrypted_card_data
required
string
object (Address)

Responses

Request samples

Content type
application/json
{
  • "digital_wallet": "issuer",
  • "tenant_customer_ref": "string",
  • "issuer_card_id": "string",
  • "wallet_id": "string",
  • "issuer_authentication_data": "string",
  • "encrypted_card_data": "string",
  • "billing_address": {
    }
}

Response samples

Content type
application/json
{
  • "wallet_id": "string",
  • "provisioning_data": { }
}

Manage Secure Device Wallets

APIs used to manage the lifecycle of secure device wallets. See Lifecycle management for more details.

Lock a secure device wallet

You can use this API to lock a secure device wallet. This will temporarily block payments and other functionalities of the wallet.

path Parameters
id
required
string <uuid>

Wallet ID(format UUID)

Request Body schema: application/json
required
reason_code
required
string (PbaLockWalletReasonCode)
Enum: "device_stolen" "device_lost" "suspected_fraud" "other"
reason
required
string

Responses

Request samples

Content type
application/json
{
  • "reason_code": "device_stolen",
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "wallet_id": "string",
  • "status": "active",
  • "status_timestamp": "2019-08-24T14:15:22Z",
  • "suspended_by": [
    ]
}

Retrieve Card Details

APIs used to retrieve sensitive virtual card details. See Display card details for more details.

Get card fetch token

This API can be used to get a card fetch token for a specific virtual card.

Request Body schema: application/json
required
static_token_id
required
string <uuid>

OF static token id

account_id
required
string

financial account id

card_encryption_key
string

Card Encryption Key for card handover

card_encryption_algo
string (CardEncryptionAlgo)
Enum: "rsa_oaep" "ecc_ecies"

Responses

Request samples

Content type
application/json
{
  • "static_token_id": "3fb159c5-3595-473f-a882-31eae6265673",
  • "account_id": "string",
  • "card_encryption_key": "string",
  • "card_encryption_algo": "rsa_oaep"
}

Response samples

Content type
application/json
{
  • "card_fetch_token": "string"
}

Retrieve card details

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.

Request Body schema: application/json
required
card_fetch_token
required
string
fetch_cvv
boolean
Default: true

It will be used to return cvv in response or not. By default its true

Responses

Request samples

Content type
application/json
{
  • "card_fetch_token": "YTZkYmJkYWItMWI3ZC00MzNhLTkzOWEtZjYzYzkwMjJmODMz"
}

Response samples

Content type
application/json
{
  • "provider": "mastercard",
  • "card_reference_id": "7743087",
  • "card_number": "5281724086788282",
  • "redacted_number": "XXXXXXXXXXXX8282",
  • "cvv": "1111",
  • "expiry_month": "12",
  • "expiry_year": "25",
  • "message": "S"
}

Display Virtual Cards

APIs used to display virtual card details securely. See Display virtual cards for more details.

Create card details widget

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.

Request Body schema: application/json
required
static_token_id
string

Either static_token_id or card_fetch_token must be provided.

card_fetch_token
string

Either static_token_id or card_fetch_token must be provided.

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.

card_art_base64
string <= 204800 characters

Base64 encoded card art image.

Max 150KB decoded. Recommended dimensions: 340x214px (or 1.586:1 aspect ratio).

Mutually exclusive with card_art_asset_id.

card_art_content_type
string (CardArtContentType)
Enum: "image/png" "image/jpeg" "image/webp"

MIME type of the card art image

Responses

Request samples

Content type
application/json
Example
{
  • "card_fetch_token": "eyJhbGciOiJIUzI1...",
  • "card_art_asset_id": "7f3a2b1c-9d4e-5f6a-8b7c-0d1e2f3a4b5c"
}

Response samples

Content type
application/json
{}

Upload card art asset

Uploads a card art image for reuse across multiple widget sessions. Returns an asset_id that can be referenced in the widget creation API.

Request Body schema: application/json
required
card_art_base64
required
string <= 204800 characters

Base64 encoded card art image.

Max 150KB decoded. Recommended dimensions: 340x214px (or 1.586:1 aspect ratio).

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").

Responses

Request samples

Content type
application/json
{
  • "card_art_base64": "string",
  • "card_art_content_type": "image/png",
  • "card_art_asset_name": "string"
}

Response samples

Content type
application/json
{
  • "card_art_asset_id": "5b16da63-879e-4cf7-ab48-113484c3053f",
  • "card_art_asset_name": "string",
  • "card_art_content_type": "image/png",
  • "size_bytes": 0,
  • "created_at": "2019-08-24T14:15:22Z"
}

List card art assets

Returns all card art assets uploaded by the tenant.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Delete card art asset

Deletes a previously uploaded card art asset. Existing widget sessions that already resolved this asset are unaffected.

path Parameters
asset_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "error_code": "string",
  • "message": "string",
  • "details": [
    ]
}

Manage Virtual Cards

APIs used to manage virtual cards. See Manage virtual cards for more details.

List virtual cards

This API can be used to list all virtual cards belonging to a customer.

Warning This API can also be used to list all virtual cards of all customers (by omitting both tenant_customer_ref and tenant_account_ref in the request parameters). This kind of query should only be used in extreme scenarios.

query Parameters
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"

Filter by instrument

status
string (StaticTokenStatus)
Enum: "active" "inactive" "deactivated"

Filter by status

locked
boolean

Filter by lock status

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get virtual card

This API can be used to get details of a specific virtual card.

path Parameters
id
required
string

Static token id

Responses

Response samples

Content type
application/json
{
  • "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": {
    },
  • "fpan_redacted_number": "string",
  • "fpan_expiry": {
    },
  • "instrument": "web_checkout",
  • "status": "active",
  • "locked": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update virtual card

This API can be used to lock or unlock a specific virtual card.

path Parameters
id
required
string

Static token id

Request Body schema: application/json
required
lock_status
required
string (StaticTokenLockStatus)
Enum: "locked" "unlocked"

Responses

Request samples

Content type
application/json
{
  • "lock_status": "locked"
}

Response samples

Content type
application/json
{
  • "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": {
    },
  • "fpan_redacted_number": "string",
  • "fpan_expiry": {
    },
  • "instrument": "web_checkout",
  • "status": "active",
  • "locked": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete virtual card

This API can be used to deactivate a specific virtual card.

Warning This action is permanent (cannot be undone) and requires the virtual card to be locked first before deleting.

path Parameters
id
required
string

Static token id

Request Body schema: application/json
required
reason_text
string
reason_code
string (PbaCustomerDpanSuspendReasonCode)
Enum: "device_lost" "device_stolen" "suspected_fraud" "other"

Responses

Request samples

Content type
application/json
{
  • "reason_text": "string",
  • "reason_code": "device_lost"
}

Response samples

Content type
application/json
{
  • "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": {
    },
  • "fpan_redacted_number": "string",
  • "fpan_expiry": {
    },
  • "instrument": "web_checkout",
  • "status": "active",
  • "locked": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Token Update Notifications

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.

OutToken activated notification

This notification is sent when an account or card was successfully tokenized and activated in the secure device wallet.

Request Body schema: application/json
required
notification_id
required
string <uuid>
type
required
string
Value: "v1:wallet:token:activated"
created_at
required
string <date-time>
required
object (WalletTokenActivatedEventNotificationPayload)

Base schema for wallet token status change notifications data

Responses

Request samples

Content type
application/json
{
  • "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
  • "type": "v1:wallet:token:activated",
  • "created_at": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

OutToken suspended notification

This notification is sent when the tokenized account or card is suspended in the secure device wallet.

Request Body schema: application/json
required
notification_id
required
string <uuid>
type
required
string
Value: "v1:wallet:token:suspended"
created_at
required
string <date-time>
required
object (WalletTokenSuspendedEventNotificationPayload)

Base schema for wallet token status change notifications data

Responses

Request samples

Content type
application/json
{
  • "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
  • "type": "v1:wallet:token:suspended",
  • "created_at": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

OutToken deleted notification

This notification is sent when the tokenized account or card is deleted from the secure device wallet.

Request Body schema: application/json
required
notification_id
required
string <uuid>
type
required
string
Value: "v1:wallet:token:deleted"
created_at
required
string <date-time>
required
object (WalletTokenDeletedEventNotificationPayload)

Base schema for wallet token status change notifications data

Responses

Request samples

Content type
application/json
{
  • "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
  • "type": "v1:wallet:token:deleted",
  • "created_at": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

OutTransaction authorization notification

This notification is sent when a transaction is authorized within the secure device wallet.

Request Body schema: application/json
required
notification_id
required
string <uuid>
type
required
string
Value: "v1:wallet:transaction:authorization"
created_at
required
string <date-time>
required
object (PbaWalletTransactionAuthorizedNotification)

v1:wallet:transaction:authorization

Responses

Request samples

Content type
application/json
{
  • "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
  • "type": "v1:wallet:transaction:authorization",
  • "created_at": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Authorization

APIs related to authorization messages. These are messages sent from our platform to your backend.

See Authorization message for more details.

OutAuthorization message

Real-time authorization messages sent to your backend for an approval/decline decision. The same schema is used for final authorizations and pre-authorizations.

See Authorization message for more details.

Request Body schema: application/json
required
transaction_id
required
string <uuid>
network_transaction_ref
required
string
customer_id
required
string <uuid>
tenant_customer_ref
required
string
tenant_account_ref
required
string
account_id
required
string <uuid>
provision_id
required
string <uuid>
provision_type
required
string (PbaAskForApprovalProvisionType)
Enum: "customer_account_device" "static_token" "google_pay" "samsung_pay" "apple_pay" "unknown"
device_id
string <uuid>
static_token_id
string
network_message_ref
required
string
network_merchant_name
required
string
network_merchant_outlet_address
required
string
network_merchant_id
required
string
network_merchant_category_code
required
string
network_acquirer_id
string

ID of the Merchant Acquirer on Mastercard Network

required
object (PbaAskForApprovalAuthIndicator)
amount
required
number

Amount in base unit

currency
required
string

Currency code (ISO 4217)

billing_amount
required
number

Billing amount in base unit

billing_currency_code
required
string

Billing currency code (ISO 4217)

billing_exchange_rate
required
number

Exchange rate when calculating billing amount

settlement_amount
number

Settlement amount in base unit

settlement_currency_code
string

Settlement currency code (ISO 4217)

settlement_exchange_rate
number

Exchange rate when calculating settlement amount

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"
transaction_category
required
string (PbaTransactionCategory)
Enum: "high_risk_purchase" "recurring_payment" "transit" "automated_fuel_dispenser" "dynamic_currency_conversion" "cardholder_activated_terminal" "other"
object (PbaAskForApprovalVerificationData)
card_on_file
boolean
partner_country_code
required
string = 2 characters

Country Code - ISO 3166 Alpha-2

payment_network
required
string (PbaPaymentNetwork)
Enum: "mastercard" "visa"
network_merchant_terminal_id
string

ID of the Merchant Terminal

network_merchant_city
string <= 40 characters

City of the Merchant Terminal

token_requestor_id
string

Indicates whether the transaction originated from the tenant's own app or a third-party wallet (e.g., Google Pay, Samsung Pay, Apple Pay).

object (AuthPolicyEvaluateResponse)

Response from policy evaluation

Responses

Request samples

Content type
application/json
{
  • "transaction_id": "6182bde8-ee3e-4bd5-935e-e56507e0f808",
  • "network_transaction_ref": "awqcB1rPDuJIm4yKOQbqJUj5MvpdcH6D",
  • "customer_id": "8e64c3c2-f409-4e0b-afb7-05cce88d26d7",
  • "tenant_customer_ref": "01HG04B4NDBB7XT9JY6H1Y2B3A",
  • "device_id": "f4e52b39-3664-48ce-844c-7a92772b1f2e",
  • "network_message_ref": "CZLIzgNfeyMCabcsXp3liJPgSVGyQypHI2A",
  • "network_merchant_name": "Merchant123456",
  • "network_merchant_id": "6000123456",
  • "network_merchant_outlet_address": "Central, Singapore",
  • "network_merchant_category_code": "1234",
  • "network_merchant_terminal_id": "4000123456",
  • "network_merchant_city": "Singapore",
  • "auth_indicator": {
    },
  • "amount": 0.1,
  • "currency": "SGD",
  • "billing_amount": 0.1,
  • "billing_currency_code": "SGD",
  • "billing_exchange_rate": 1,
  • "settlement_amount": 0.1,
  • "settlement_currency_code": "SGD",
  • "settlement_exchange_rate": 1,
  • "transaction_source": "terminal",
  • "transaction_category": "transit",
  • "verification_data": {
    },
  • "partner_country_code": "SG"
}

Response samples

Content type
application/json
{
  • "tenant_reference_id": "31XXXX6723173605",
  • "approved_amount": 20,
  • "authorization_code": "8ABJ6S",
  • "status": "approved",
  • "reason": null
}

Ledger Operations

Ledger operations that Open Fabric calls on your backend to apply balance changes (debit/credit/hold/release).

See Ledger APIs for more details.

OutDebit balance

debit_balance: Deduct funds from a customer’s balance for settlement.

Request Body schema: application/json
required
transaction_id
required
string

Unique identifier for the transaction

tenant_account_ref
required
string

Identifier of the tenant account

idempotency_key
required
string

Unique identifier to prevent duplicate operations

object (BalanceAmount)

Amount object used in balance operations

of_action_ref
required
string

OpenFabric reference identifier for the operation

tenant_balance_ref
string

Reference of the exact balance to be debited (used in refund reversal)

Responses

Request samples

Content type
application/json
{
  • "transaction_id": "string",
  • "tenant_account_ref": "string",
  • "idempotency_key": "string",
  • "amount": {
    },
  • "of_action_ref": "string",
  • "tenant_balance_ref": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "tenant_balance_ref": "string",
  • "available_balance": {
    },
  • "tenant_action_ref": "string",
  • "error": {
    }
}

OutCredit balance

credit_balance: Add funds to a customer’s balance (for refunds or adjustments).

Request Body schema: application/json
required
transaction_id
required
string

Unique identifier for the transaction

tenant_account_ref
required
string

Identifier of the tenant account

idempotency_key
required
string

Unique identifier to prevent duplicate operations

object (BalanceAmount)

Amount object used in balance operations

of_action_ref
required
string

OpenFabric reference identifier for the operation

tenant_balance_ref
string

Reference of the exact balance to be credited (used in auth reversal)

Responses

Request samples

Content type
application/json
{
  • "transaction_id": "string",
  • "tenant_account_ref": "string",
  • "idempotency_key": "string",
  • "amount": {
    },
  • "of_action_ref": "string",
  • "tenant_balance_ref": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "tenant_balance_ref": "string",
  • "available_balance": {
    },
  • "tenant_action_ref": "string",
  • "error": {
    }
}

OutHold balance

hold_balance: Place a hold on funds in a customer’s balance (pre-authorization).

Request Body schema: application/json
required
transaction_id
required
string

Unique identifier for the transaction

tenant_account_ref
required
string

Identifier of the tenant account

idempotency_key
required
string

Unique identifier to prevent duplicate operations

object (BalanceAmount)

Amount object used in balance operations

of_action_ref
required
string

OpenFabric reference identifier for the operation

tenant_hold_balance_ref
string

Reference of the hold funds balance to be increased (used in pre-auth incremental)

Responses

Request samples

Content type
application/json
{
  • "transaction_id": "string",
  • "tenant_account_ref": "string",
  • "idempotency_key": "string",
  • "amount": {
    },
  • "of_action_ref": "string",
  • "tenant_hold_balance_ref": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "tenant_hold_balance_ref": "string",
  • "available_balance": {
    },
  • "tenant_action_ref": "string",
  • "error": {
    }
}

OutRestore balance

restore_balance: Release previously held funds back to available balance.

Request Body schema: application/json
required
transaction_id
required
string

Unique identifier for the transaction

tenant_account_ref
required
string

Identifier of the tenant account

idempotency_key
required
string

Unique identifier to prevent duplicate operations

object (BalanceAmount)

Amount object used in balance operations

of_action_ref
required
string

OpenFabric reference identifier for the operation

tenant_hold_balance_ref
required
string

Reference of the hold funds balance to be released (required)

Responses

Request samples

Content type
application/json
{
  • "transaction_id": "string",
  • "tenant_account_ref": "string",
  • "idempotency_key": "string",
  • "amount": {
    },
  • "of_action_ref": "string",
  • "tenant_hold_balance_ref": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "tenant_balance_ref": "string",
  • "available_balance": {
    },
  • "tenant_action_ref": "string",
  • "error": {
    }
}

OutDebit hold balance

debit_hold_balance: Deduct an amount from previously held funds (created with hold_balance).

Request Body schema: application/json
required
transaction_id
required
string

Unique identifier for the transaction

tenant_account_ref
required
string

Identifier of the tenant account

idempotency_key
required
string

Unique identifier to prevent duplicate operations

object (BalanceAmount)

Amount object used in balance operations

of_action_ref
required
string

OpenFabric reference identifier for the operation

tenant_hold_balance_ref
required
string

Reference of the hold funds balance to be debited (required)

Responses

Request samples

Content type
application/json
{
  • "transaction_id": "string",
  • "tenant_account_ref": "string",
  • "idempotency_key": "string",
  • "amount": {
    },
  • "of_action_ref": "string",
  • "tenant_hold_balance_ref": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "tenant_hold_balance_ref": "string",
  • "hold_balance": {
    },
  • "tenant_action_ref": "string",
  • "error": {
    }
}

OutCredit hold balance

credit_hold_balance: Add an amount to previously held funds (created with hold_balance).

Request Body schema: application/json
required
transaction_id
required
string

Unique identifier for the transaction

tenant_account_ref
required
string

Identifier of the tenant account

idempotency_key
required
string

Unique identifier to prevent duplicate operations

object (BalanceAmount)

Amount object used in balance operations

of_action_ref
required
string

OpenFabric reference identifier for the operation

tenant_hold_balance_ref
required
string

Reference of the hold funds balance to be credited (required)

Responses

Request samples

Content type
application/json
{
  • "transaction_id": "string",
  • "tenant_account_ref": "string",
  • "idempotency_key": "string",
  • "amount": {
    },
  • "of_action_ref": "string",
  • "tenant_hold_balance_ref": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "tenant_hold_balance_ref": "string",
  • "hold_balance": {
    },
  • "tenant_action_ref": "string",
  • "error": {
    }
}

Reversal Notifications

Notifications related to reversals. These are messages sent from our platform to your backend.

See Reversal notifications for more details.

OutFinal authorization reversal notification

Notification sent when a previously approved final authorization is reversed.

See Reversal notifications for more details.

Request Body schema: application/json
required
notification_id
required
string <uuid>
type
required
string
Value: "v1:pba:transaction:final_auth_reversed"
created_at
required
string <date-time>
required
object (FinalAuthReversalNotification)

v1:pba:transaction:final_auth_reversed

Responses

Request samples

Content type
application/json
{
  • "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
  • "type": "v1:pba:transaction:final_auth_reversed",
  • "created_at": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

OutPre-authorization reversal notification

Notification sent when a previously approved pre-authorization is reversed.

See Reversal notifications for more details.

Request Body schema: application/json
required
notification_id
required
string <uuid>
type
required
string
Value: "v1:pba:transaction:pre_auth_reversed"
created_at
required
string <date-time>
required
object (PreAuthReversalNotification)

v1:pba:transaction:pre_auth_reversed

Responses

Request samples

Content type
application/json
{
  • "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
  • "type": "v1:pba:transaction:pre_auth_reversed",
  • "created_at": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

OutAuthorization failed notification

Notification sent when an authorization could not be completed successfully (e.g. due to timeout or non-200 from your approval endpoint) and was declined on your behalf.

See Reversal notifications for more details.

Request Body schema: application/json
required
notification_id
required
string <uuid>
type
required
string
Value: "v1:pba:transaction:authorization_failed"
created_at
required
string <date-time>
required
object (PbaAuthorizationFailedNotification)

v1:pba:transaction:authorization_failed

Responses

Request samples

Content type
application/json
{
  • "notification_id": "3e6dd7ab-3360-4269-821e-a591bc94232c",
  • "type": "v1:pba:transaction:authorization_failed",
  • "created_at": "2024-06-06T18:47:21.175Z",
  • "data": {
    }
}

3D Secure

APIs and messages used to complete 3D Secure challenges during payment processing.

See Handle 3D Secure Payments for more details.

OutOut-of-band (OOB) challenge request

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.

Request Body schema: application/json
required
three_ds_challenge_id
required
string

three_ds_logs.id

tenant_customer_ref
required
string
customer_id
required
string
tenant_account_ref
required
string
account_id
required
string
static_token_id
required
string
merchant_name
required
string
transaction_amount
required
number
transaction_currency
required
string
creation_time
required
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "three_ds_challenge_id": "string",
  • "tenant_customer_ref": "string",
  • "customer_id": "string",
  • "tenant_account_ref": "string",
  • "account_id": "string",
  • "static_token_id": "string",
  • "merchant_name": "string",
  • "transaction_amount": 0,
  • "transaction_currency": "string",
  • "creation_time": "2019-08-24T14:15:22Z"
}

Out of Band (OOB) challenge response

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.

Request Body schema: application/json
required
three_ds_challenge_id
required
string
static_token_id
required
string
tenant_customer_ref
required
string
tenant_account_ref
required
string
challenge_result
required
string (ThreeDsActionResult)
Enum: "pending" "approved" "declined" "cancelled"
reason
string
creation_time
required
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "three_ds_challenge_id": "string",
  • "static_token_id": "string",
  • "tenant_customer_ref": "string",
  • "tenant_account_ref": "string",
  • "challenge_result": "pending",
  • "reason": "string",
  • "creation_time": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "error_code": "string",
  • "message": "string",
  • "details": [
    ]
}

OutSend OTP request

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.

Request Body schema: application/json
required
three_ds_challenge_id
required
string

three_ds_logs.id

tenant_customer_ref
required
string
customer_id
required
string
tenant_account_ref
required
string
account_id
required
string
static_token_id
required
string
merchant_name
required
string
transaction_amount
required
number
transaction_currency
required
string
creation_time
required
string <date-time>
authentication_credential
string
encrypted_authentication_credential
string

Responses

Request samples

Content type
application/json
{
  • "three_ds_challenge_id": "string",
  • "tenant_customer_ref": "string",
  • "customer_id": "string",
  • "tenant_account_ref": "string",
  • "account_id": "string",
  • "static_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"
}

Response samples

Content type
application/json
{
  • "three_ds_challenge_id": "string",
  • "masked_email": "string",
  • "masked_phone_number": "string"
}

Clearing

Messages related to clearing. These are messages sent from our platform to your backend via notifications and reporting.

See Clearing operations for more details.

Clearing record

network_clearing_ref
required
string
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"
transfer_type
required
string (PbaTransferType)
Enum: "consumer_debit" "consumer_credit" "ahi_debit" "ahi_credit"
is_potential_chargeback
required
boolean
original_transaction_id
string
transaction_id
string

Transaction ID of this transaction itself. Used for action mapping workflow dispatch.

network_transaction_ref
string
network_acquirer_transaction_ref
string
original_tenant_transaction_ref
string
customer_id
string
tenant_account_ref
string
tenant_customer_ref
string
network_merchant_name
required
string
network_merchant_outlet_address
required
string
network_merchant_id
required
string
amount
required
number
currency
required
string
billing_amount
required
number
billing_currency_code
required
string
billing_exchange_rate
required
number
settlement_amount
required
number
settlement_currency_code
required
string
settlement_exchange_rate
required
number
interchange_fee_amount
required
number
interchange_fee_currency_code
required
string
network_clearing_file_ref
required
string
network_clearing_file_name
required
string
network_clearing_timestamp
required
string
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"
network_posting_file_id
required
string

Mastercard's identifier of the GCMS file in which the transaction appeared

network_merchant_category_code
string

Type of services or goods the Merchant provides for the transaction

network_acquirer_id
required
string

Acquirer identification of the transaction

network_merchant_country_code
string

Country Code - ISO 3166 Alpha-2

is_converted_pre_auth
required
boolean

Indicates if this is a converted pre-authorization transaction

network_merchant_terminal_id
string

ID of the Merchant Terminal

network_merchant_city
string

City of the Merchant Terminal

{
  • "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_account_ref": "string",
  • "tenant_customer_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",
  • "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"
}

OutClearing file ready notification

Notification sent when a clearing file is ready to be processed.

Request Body schema: application/json
required
notification_id
required
string <uuid>
type
required
string
Value: "v1:pba:eoc:clearing_file_ready"
created_at
required
string <date-time>
required
object (EOCFileProcessedNotification)

v1:pba:eoc:clearing_file_ready

Responses

Request samples

Content type
application/json
{
  • "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
  • "type": "v1:pba:eoc:clearing_file_ready",
  • "created_at": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Settlement

Messages related to settlement. These are messages sent from our platform to your backend via notifications and reporting.

See Settlement for more details.

Settlement Report

required
object (ReconciliationAndNetSettlementSummary)
required
Array of objects (SettlementRecordDetail)
{
  • "reconciliationAndNetSettlementSummary": {
    },
  • "settlementRecordDetails": [
    ]
}

OutSettlement file ready notification

Notification sent when a settlement file is ready to be processed.

Request Body schema: application/json
required
notification_id
required
string <uuid>
type
required
string
Value: "v1:pba:eos:net_settlement_file_ready"
created_at
required
string <date-time>
required
object (EOSNetSettlementNotification)

v1:pba:eos:net_settlement_file_ready

Responses

Request samples

Content type
application/json
{
  • "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
  • "type": "v1:pba:eos:net_settlement_file_ready",
  • "created_at": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Transaction orchestration

APIs you use to approve/decline and query transactions during online orchestration.

See Orchestrated integration guide for the end-to-end flow.

OutTransaction request

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.

Request Body schema: application/json
required
One of
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

Responses

Request samples

Content type
application/json
{
  • "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",
  • "gateway_success_url": "https://gateway.dev.openfabric.co",
  • "gateway_fail_url": "https://gateway.dev.openfabric.co",
  • "customer_info": {
    },
  • "amount": 120.1,
  • "currency": "SGD",
  • "transaction_details": {
    },
  • "pat_link": {
    },
  • "partner_name": "string",
  • "source": "string"
}

Response samples

Content type
application/json
{}

Approve / Decline a transaction

Tenant can call this API to approve or fail a transaction.

Request Body schema: application/json
required

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

Responses

Request samples

Content type
application/json
Example
{
  • "tenant_reference_id": "cd992711-498f-47be-b636-cf2e3eaad935",
  • "status": "approved"
}

Response samples

Content type
application/json
{
  • "error_code": "string",
  • "message": "string",
  • "details": [
    ]
}

Get a transaction data

This API can be used to fetch a transaction

path Parameters
id
required
string <uuid>

OpenFabric Generated ID for this Transaction. You will receive this part of Update Transaction Response.

Responses

Response samples

Content type
application/json
{}

Get a transaction detailed data

This API can be used to fetch transaction with all details including card, customer and transaction information submitted by Partner.

path Parameters
id
required
string <uuid>

OpenFabric Generated ID for this Transaction. You will receive this part of Update Transaction Response.

Responses

Response samples

Content type
application/json
{
  • "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_fail_url": "http://of-gateway",
  • "gateway_success_url": "http://of-gateway.s3-website-ap-southeast-1.amazonaws.com?reference_id=P1293201980299030&state=PAID",
  • "payment_redirect_web_url": "http://sample-bnpl-web.openfabric.co",
  • "card": {
    },
  • "customer_id": "88db7aa7-2cdd-42cc-9827-8d46f936ef79",
  • "customer_info": {
    },
  • "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": {
    }
}

OutTransaction charged update

Callback sent to your backend after a one-time payment credential is charged successfully.

Request Body schema: application/json
required
Array
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

Responses

Request samples

Content type
application/json
[
  • {
    }
]

OutTransaction reversed update

Callback sent to your backend when a reversal or refund is issued against a one-time payment credential.

Request Body schema: application/json
required
Array
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)

Responses

Request samples

Content type
application/json
[
  • {
    }
]

OutTransaction credited update

Callback sent to your backend when a transaction is credited.

Request Body schema: application/json
required
Array
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)

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Callback subscriptions

APIs to manage your callback (webhook) subscriptions for online-orchestration updates.

List all webhook subscriptions

List all webhook subscriptions for Tenant

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Create a webhook subscription

Create a webhook subscription for Tenant

query Parameters
webhook_type
string (WebhookType)
Enum: "online" "pat_provision"

Webhook type

Request Body schema: application/json
required

Notification subscription object to init

config
required
object

Configuration options for the subscription

subscribed_events
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "type": "webhook",
  • "subscribed_events": [
    ],
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "id": "cd992711-498f-47be-b636-cf2e3eaad935",
  • "tenant_id": "00fcf093-71fb-4349-8c0b-de810480d6b1",
  • "type": "webhook",
  • "subscribed_events": [
    ],
  • "config": {
    }
}

Update a subscription

Update an existing webhook subscription for Tenant

path Parameters
id
required
string <uuid>

ID of an existing notification subscription

query Parameters
webhook_type
string (WebhookType)
Enum: "online" "pat_provision"

Webhook type

Request Body schema: application/json
required

Notification subscription object to update

config
required
object

Configuration options for the subscription

subscribed_events
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "type": "webhook",
  • "subscribed_events": [
    ],
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "id": "cd992711-498f-47be-b636-cf2e3eaad935",
  • "tenant_id": "00fcf093-71fb-4349-8c0b-de810480d6b1",
  • "type": "webhook",
  • "subscribed_events": [
    ],
  • "config": {
    }
}

Partner management

APIs to create, update, list, and deactivate merchants/payment gateways (“partners”) that integrate with Open Fabric.

See Partner onboarding and management APIs.

List all Partners

Get all Partners associated with current Tenant

query Parameters
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

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "metadata": {
    }
}

Create a Partner

Create a Partner

Request Body schema: application/json
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]$
email
string <email>
website_url
required
string <uri>
category
string
country
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "tenant_partner_id": "string",
  • "slug": "string",
  • "email": "user@example.com",
  • "website_url": "http://example.com",
  • "category": "string",
  • "country": "string"
}

Response samples

Content type
application/json
{
  • "id": "4fde45e1-6e4f-4039-a8de-bb316a4adeb8",
  • "name": "Lazada",
  • "tenant_partner_id": "4fde45e1-6e4f-4039-a8de-bb316a4adeb8",
  • "slug": "lazada",
  • "website_url": "https://www.lazada.co.th/"
}

Get a Partner details

Get a Partner details

path Parameters
partner_id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "4fde45e1-6e4f-4039-a8de-bb316a4adeb8",
  • "tenant_partner_id": "4fde45e1-6e4f-4039-a8de-bb316a4adeb8",
  • "name": "Lazada",
  • "slug": "lazada",
  • "website_url": "https://www.lazada.co.th/",
  • "email": "admin@lazada.co.th"
}

Update a Partner

Update a Partner with the current Tenant

path Parameters
partner_id
required
string
Request Body schema: application/json
required

Body request to update Partner for Tenant

name
string
website_url
string <uri>
category
string
country
string
email
string <email>
tenant_partner_id
string [ 4 .. 36 ] characters ^[a-zA-Z0-9\-_@\.]*$

Responses

Request samples

Content type
application/json
{
  • "tenant_partner_id": "4fde45e1-6e4f-4039-a8de-bb316a4adeb8",
  • "name": "Lazada",
  • "website_url": "https://www.lazada.co.th/",
  • "email": "admin@lazada.co.th"
}

Response samples

Content type
application/json
{
  • "id": "4fde45e1-6e4f-4039-a8de-bb316a4adeb8",
  • "tenant_partner_id": "4fde45e1-6e4f-4039-a8de-bb316a4adeb8",
  • "name": "Lazada",
  • "slug": "lazada",
  • "website_url": "https://www.lazada.co.th/",
  • "email": "admin@lazada.co.th"
}

Deactivate a Partner

Delete Partner association with the current Tenant

path Parameters
partner_id
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "ok"
}

Partner settings

APIs to manage partner credentials, callback subscriptions, and payment gateway credentials used for token handover.

See Partner onboarding and management APIs.

Credential: Retrieve API credentials

Retrieve API credentials of a Partner

path Parameters
partner_id
required
string <uuid>

Partner ID

alias
required
string^[\S]+$

Alias for the credentials

Responses

Response samples

Content type
application/json
{
  • "alias": "default",
  • "client_id": "id119i9d8ekasjc9x",
  • "client_secret": "secret3jjsj3jdjk2jkesk"
}

Credential: Renew API credentials

Revoke and request new API credentials of a Partner

path Parameters
partner_id
required
string <uuid>

Partner ID

alias
required
string^[\S]+$

Alias for the credentials

Responses

Response samples

Content type
application/json
{
  • "alias": "default",
  • "client_id": "id119i9d8ekasjc9x",
  • "client_secret": "secret3jjsj3jdjk2jkesk"
}

Webhook: Create a webhook subscription

Create a webhook subscription for a Partner

path Parameters
partner_id
required
string <uuid>

Partner ID

query Parameters
webhook_type
string (WebhookType)
Enum: "online" "pat_provision"

Webhook type

Request Body schema: application/json
required

Notification subscription object to init

config
required
object

Configuration options for the subscription

subscribed_events
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "type": "webhook",
  • "subscribed_events": [
    ],
  • "config": {}
}

Response samples

Content type
application/json
{
  • "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": {}
}

Webhook: Update a subscription

Update a webhook subscription of a Partner

path Parameters
partner_id
required
string <uuid>

Partner ID

id
required
string <uuid>

ID of an existing notification subscription

query Parameters
webhook_type
string (WebhookType)
Enum: "online" "pat_provision"

Webhook type

Request Body schema: application/json
required

Notification subscription object to update

config
required
object

Configuration options for the subscription

subscribed_events
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "type": "webhook",
  • "subscribed_events": [
    ],
  • "config": {}
}

Response samples

Content type
application/json
{
  • "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": {}
}

PG: List all PG credentials

List all PG credentials of a Partner

path Parameters
partner_id
required
string <uuid>

Partner ID

query Parameters
pg_name
string^[\S]+$

pg name

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

PG: Create/Update credentials for a PG

Update a PG credential for a PG of a Partner

path Parameters
partner_id
required
string <uuid>

Partner ID

pg_name
required
string^[\S]+$

PG name

Request Body schema: application/json
required
credential_format
required
string (CredentialFormat)
Value: "api_key_pair"
ApiKeyPGCredential (object) (PGCredentialData)
object
object (ChargeConfig)

Responses

Request samples

Content type
application/json
{
  • "value": {
    }
}

Response samples

Content type
application/json
{
  • "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": {
    },
  • "additional_params": {
    },
  • "charge_config": {
    }
}

PG: Get credentials for a PG

Get a PG credential for a PG of Partner

path Parameters
partner_id
required
string <uuid>

Partner ID

pg_name
required
string^[\S]+$

PG name

Responses

Response samples

Content type
application/json
{
  • "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": {
    },
  • "additional_params": {
    },
  • "charge_config": {
    }
}

PG: Delete credentials for a PG

Delete credentials for a PG of a Partner

path Parameters
partner_id
required
string <uuid>

Partner ID

pg_name
required
string^[\S]+$

PG name

Responses

Response samples

Content type
application/json
{
  • "error_code": "string",
  • "message": "string",
  • "details": [
    ]
}

Whitelable: Get config

Get whitelabel config of a Partner

path Parameters
partner_id
required
string <uuid>

Partner ID

Responses

Response samples

Content type
application/json
{
  • "features": [
    ]
}

Whitelabel: Update config

Update whitelabel config of a Partner

path Parameters
partner_id
required
string <uuid>

Partner ID

Request Body schema: application/json
Array of objects
Array
property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "features": [
    ]
}

Response samples

Content type
application/json
{
  • "features": [
    ]
}

Whitelabel: Retrieve widget

QuerRetrievey widget info to display for a Partner

Request Body schema: application/json
tenant_partner_id
required
string [ 4 .. 36 ] characters ^[a-zA-Z0-9\-_@\.]*$
types
Array of strings (WidgetQueryRequestType)
Items Enum: "whitelabel" "net_settlement"

Responses

Request samples

Content type
application/json
{
  • "tenant_partner_id": "string",
  • "types": [
    ]
}

Response samples

Content type
application/json
[]

Get configurations metadata for PG

Get configuration metadata for PG

Responses

Response samples

Content type
application/json
{ }

Merchant / gateway orchestration

APIs that merchants and payment gateways use with the Open Fabric Merchant SDK to create and manage transactions.

See Merchant / gateway integration guides.

Create a transaction

This will be called by Partner to initialize a transaction before interacting with payment methods

query Parameters
txn_trace_id
string <uuid>

Trace UUID (v4) to follow payment sessions

header Parameters
Idempotency-Key
string

Unique value submitted by the client to ensure idempotent request when creating transaction.

Request Body schema: application/json
required

Transaction object to init

instrument
string
Default: "web_checkout"

Instrument of the transaction request. Can be omitted for the web_checkout transaction request.

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

Responses

Request samples

Content type
application/json
{
  • "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": {
    },
  • "amount": 120.1,
  • "currency": "SGD",
  • "transaction_details": {
    }
}

Response samples

Content type
application/json
{}

Get transaction details

This will return Detailed Transaction by Open Fabric Reference ID

path Parameters
id
required
string <uuid>
query Parameters
txn_trace_id
string <uuid>

Trace UUID (v4) to follow payment sessions

Responses

Response samples

Content type
application/json
{}

Refund a transaction

This will refund a transaction that was charged by Open Fabric on behalf of Partner

path Parameters
id
required
string <uuid>
header Parameters
Idempotency-Key
string

Unique value submitted by the partner to ensure idempotent request when refunding transaction.

Request Body schema: application/json
required

Refund request body

amount
required
number >= 0.001

Refund amount

additional_properties
object
reason
string

Responses

Request samples

Content type
application/json
{
  • "amount": 10.1,
  • "reason": "Out of goods"
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get transaction by partner reference id

This will fetch the transaction by partner reference id

query Parameters
partner_reference_id
required
string

Responses

Response samples

Content type
application/json
{}

Get payment method metadata

With the payment methods input, we identify Partner by access_token, only payment methods available with this Partner will be returned

query Parameters
txn_trace_id
string <uuid>

Trace UUID (v4) to follow payment sessions

Responses

Response samples

Content type
application/json
{
  • "value": [
    ]
}

OutTransaction approved notification

Notification sent to your partner's backend when a transaction is approved.

Request Body schema: application/json
required
txn_id
required
string <uuid>

OpenFabric Transaction ID

txn_ref_id
required
string <uuid>

Transaction reference ID. Internally it is the equivalent of partner_reference_id

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 card_fetch_token

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

Responses

Request samples

Content type
application/json
{
  • "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"
}

OutTransaction failed notification

Notification sent to your partner's backend when a transaction is failed.

Request Body schema: application/json
required
txn_id
required
string <uuid>

OpenFabric Transaction ID

txn_ref_id
required
string <uuid>

Transaction reference ID. Internally it is the equivalent of partner_reference_id

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.

Responses

Request samples

Content type
application/json
{
  • "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"
}

Merchant / gateway settings

APIs that merchants and payment gateways use to manage their integration settings.

See Merchant / gateway integration guides.

Update settings

Update webhook subscription and PG credentials settings of a Partner

Request Body schema: application/json
required

Webhook and PG credentials details request for Partner

object (AccountNotificationSubscriptionRequest)
object

Responses

Request samples

Content type
application/json
{
  • "value": {
    }
}

Response samples

Content type
application/json
{
  • "webhook": {
    },
  • "payment_gateway": {
    }
}