{ "swagger": "2.0", "info": { "title": "Transcore Merchant API", "version": "v1", "description": "Transcore Merchant API" }, "consumes": [ "application/json" ], "produces": [ "application/json" ], "paths": { "/merchant/api/v1/catalog": { "get": { "operationId": "LedgerMerchants_GetMarketCatalog", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/merchantsGetMarketCatalogResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } } } }, "/merchant/api/v1/payins/authorize-otp": { "post": { "operationId": "LedgerMerchants_AuthorizeOtp", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/merchantsAuthorizeOtpResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/merchantsAuthorizeOtpRequest" } } ] } }, "/merchant/api/v1/payins/banks": { "get": { "operationId": "LedgerMerchants_ListPayInBanks", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/merchantsListPayInBanksResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "paymentMethod", "description": " - PAYMENT_METHOD_CARD: temporary not supported for pay in and payout\n - PAYMENT_METHOD_BANK_ACCOUNT: pay with bank and payout to bank account\navailable for pay in and payout\n - PAYMENT_METHOD_BANK_TRANSFER: available for pay in\n - PAYMENT_METHOD_MOBILE_MONEY: available for pay in and payout\n - PAYMENT_METHOD_MOBILE_MONEY_TRANSFER: customer-initiated mobile money transfer; available for pay in", "in": "query", "required": false, "type": "string", "enum": [ "PAYMENT_METHOD_UNSPECIFIED", "PAYMENT_METHOD_CARD", "PAYMENT_METHOD_BANK_ACCOUNT", "PAYMENT_METHOD_BANK_TRANSFER", "PAYMENT_METHOD_MOBILE_MONEY", "PAYMENT_METHOD_MOBILE_MONEY_TRANSFER" ], "default": "PAYMENT_METHOD_UNSPECIFIED" }, { "name": "countryCode", "description": "ISO 3166-1 alpha-2 country code of the payment market, for example NG, KE, GM, MW.", "in": "query", "required": false, "type": "string" }, { "name": "trafficVertical", "description": "Vertical of merchant traffic.", "in": "query", "required": false, "type": "string", "enum": [ "TRAFFIC_VERTICAL_UNSPECIFIED", "TRAFFIC_VERTICAL_GAMBLING", "TRAFFIC_VERTICAL_FOREX", "TRAFFIC_VERTICAL_OTHER" ], "default": "TRAFFIC_VERTICAL_UNSPECIFIED" }, { "name": "customerSegment", "description": "Customer segment.", "in": "query", "required": false, "type": "string", "enum": [ "CUSTOMER_SEGMENT_UNSPECIFIED", "CUSTOMER_SEGMENT_FTD", "CUSTOMER_SEGMENT_TRUSTED", "CUSTOMER_SEGMENT_VIP" ], "default": "CUSTOMER_SEGMENT_UNSPECIFIED" } ] } }, "/merchant/api/v1/payins/create": { "post": { "summary": "Create a pay-in order for direct server-to-server processing.", "operationId": "LedgerMerchants_CreatePayInOrder", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/merchantsCreatePayInOrderResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "413": { "description": "Request body exceeds the supported 1 MiB payment-creation limit.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/merchantsCreatePayInOrderRequest" } } ] } }, "/merchant/api/v1/payins/initialize": { "post": { "summary": "Initialize a hosted-checkout pay-in order.", "operationId": "LedgerMerchants_InitializePayInOrder", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/merchantsInitializePayInResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "413": { "description": "Request body exceeds the supported 1 MiB payment-creation limit.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/merchantsInitializePayInRequest" } } ] } }, "/merchant/api/v1/payins/mmo": { "get": { "operationId": "LedgerMerchants_ListPayInMMO", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/merchantsListPayInMMOResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "paymentMethod", "description": " - PAYMENT_METHOD_CARD: temporary not supported for pay in and payout\n - PAYMENT_METHOD_BANK_ACCOUNT: pay with bank and payout to bank account\navailable for pay in and payout\n - PAYMENT_METHOD_BANK_TRANSFER: available for pay in\n - PAYMENT_METHOD_MOBILE_MONEY: available for pay in and payout\n - PAYMENT_METHOD_MOBILE_MONEY_TRANSFER: customer-initiated mobile money transfer; available for pay in", "in": "query", "required": false, "type": "string", "enum": [ "PAYMENT_METHOD_UNSPECIFIED", "PAYMENT_METHOD_CARD", "PAYMENT_METHOD_BANK_ACCOUNT", "PAYMENT_METHOD_BANK_TRANSFER", "PAYMENT_METHOD_MOBILE_MONEY", "PAYMENT_METHOD_MOBILE_MONEY_TRANSFER" ], "default": "PAYMENT_METHOD_UNSPECIFIED" }, { "name": "countryCode", "description": "ISO 3166-1 alpha-2 country code of the payment market, for example KE, TZ, GM, MW.", "in": "query", "required": false, "type": "string" }, { "name": "trafficVertical", "description": "Vertical of merchant traffic.", "in": "query", "required": false, "type": "string", "enum": [ "TRAFFIC_VERTICAL_UNSPECIFIED", "TRAFFIC_VERTICAL_GAMBLING", "TRAFFIC_VERTICAL_FOREX", "TRAFFIC_VERTICAL_OTHER" ], "default": "TRAFFIC_VERTICAL_UNSPECIFIED" }, { "name": "customerSegment", "description": "Customer segment.", "in": "query", "required": false, "type": "string", "enum": [ "CUSTOMER_SEGMENT_UNSPECIFIED", "CUSTOMER_SEGMENT_FTD", "CUSTOMER_SEGMENT_TRUSTED", "CUSTOMER_SEGMENT_VIP" ], "default": "CUSTOMER_SEGMENT_UNSPECIFIED" } ] } }, "/merchant/api/v1/payment/by-reference/{merchantReference}": { "get": { "operationId": "LedgerMerchants_GetPaymentOrderByReference", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/ledgerPaymentOrder" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "merchantReference", "description": "Merchant-provided reference stored on the payment order.", "in": "path", "required": true, "type": "string" } ] } }, "/merchant/api/v1/payment/{id}": { "get": { "operationId": "LedgerMerchants_GetPaymentOrder", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/ledgerPaymentOrder" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "type": "string" } ] } }, "/merchant/api/v1/payouts/banks": { "get": { "operationId": "LedgerMerchants_ListPayOutBanks", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/merchantsListPayOutBanksResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "paymentMethod", "description": " - PAYMENT_METHOD_CARD: temporary not supported for pay in and payout\n - PAYMENT_METHOD_BANK_ACCOUNT: pay with bank and payout to bank account\navailable for pay in and payout\n - PAYMENT_METHOD_BANK_TRANSFER: available for pay in\n - PAYMENT_METHOD_MOBILE_MONEY: available for pay in and payout\n - PAYMENT_METHOD_MOBILE_MONEY_TRANSFER: customer-initiated mobile money transfer; available for pay in", "in": "query", "required": false, "type": "string", "enum": [ "PAYMENT_METHOD_UNSPECIFIED", "PAYMENT_METHOD_CARD", "PAYMENT_METHOD_BANK_ACCOUNT", "PAYMENT_METHOD_BANK_TRANSFER", "PAYMENT_METHOD_MOBILE_MONEY", "PAYMENT_METHOD_MOBILE_MONEY_TRANSFER" ], "default": "PAYMENT_METHOD_UNSPECIFIED" }, { "name": "countryCode", "description": "ISO 3166-1 alpha-2 country code of the payment market, for example NG, KE, GM, MW.", "in": "query", "required": false, "type": "string" }, { "name": "trafficVertical", "description": "Vertical of merchant traffic.", "in": "query", "required": false, "type": "string", "enum": [ "TRAFFIC_VERTICAL_UNSPECIFIED", "TRAFFIC_VERTICAL_GAMBLING", "TRAFFIC_VERTICAL_FOREX", "TRAFFIC_VERTICAL_OTHER" ], "default": "TRAFFIC_VERTICAL_UNSPECIFIED" }, { "name": "customerSegment", "description": "Customer segment.", "in": "query", "required": false, "type": "string", "enum": [ "CUSTOMER_SEGMENT_UNSPECIFIED", "CUSTOMER_SEGMENT_FTD", "CUSTOMER_SEGMENT_TRUSTED", "CUSTOMER_SEGMENT_VIP" ], "default": "CUSTOMER_SEGMENT_UNSPECIFIED" } ] } }, "/merchant/api/v1/payouts/create": { "post": { "operationId": "LedgerMerchants_CreatePayOutOrder", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/merchantsCreatePayOutOrderResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "413": { "description": "Request body exceeds the supported 1 MiB payment-creation limit.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/merchantsCreatePayOutOrderRequest" } } ] } }, "/merchant/api/v1/payouts/mmo": { "get": { "operationId": "LedgerMerchants_ListPayOutMMO", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/merchantsListPayOutMMOResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "paymentMethod", "description": " - PAYMENT_METHOD_CARD: temporary not supported for pay in and payout\n - PAYMENT_METHOD_BANK_ACCOUNT: pay with bank and payout to bank account\navailable for pay in and payout\n - PAYMENT_METHOD_BANK_TRANSFER: available for pay in\n - PAYMENT_METHOD_MOBILE_MONEY: available for pay in and payout\n - PAYMENT_METHOD_MOBILE_MONEY_TRANSFER: customer-initiated mobile money transfer; available for pay in", "in": "query", "required": false, "type": "string", "enum": [ "PAYMENT_METHOD_UNSPECIFIED", "PAYMENT_METHOD_CARD", "PAYMENT_METHOD_BANK_ACCOUNT", "PAYMENT_METHOD_BANK_TRANSFER", "PAYMENT_METHOD_MOBILE_MONEY", "PAYMENT_METHOD_MOBILE_MONEY_TRANSFER" ], "default": "PAYMENT_METHOD_UNSPECIFIED" }, { "name": "countryCode", "description": "ISO 3166-1 alpha-2 country code of the payment market, for example KE, TZ, GM, MW.", "in": "query", "required": false, "type": "string" }, { "name": "trafficVertical", "description": "Vertical of merchant traffic.", "in": "query", "required": false, "type": "string", "enum": [ "TRAFFIC_VERTICAL_UNSPECIFIED", "TRAFFIC_VERTICAL_GAMBLING", "TRAFFIC_VERTICAL_FOREX", "TRAFFIC_VERTICAL_OTHER" ], "default": "TRAFFIC_VERTICAL_UNSPECIFIED" }, { "name": "customerSegment", "description": "Customer segment.", "in": "query", "required": false, "type": "string", "enum": [ "CUSTOMER_SEGMENT_UNSPECIFIED", "CUSTOMER_SEGMENT_FTD", "CUSTOMER_SEGMENT_TRUSTED", "CUSTOMER_SEGMENT_VIP" ], "default": "CUSTOMER_SEGMENT_UNSPECIFIED" } ] } }, "/merchant/api/v2/balances": { "get": { "operationId": "LedgerMerchants_ListBalancesV2", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/merchantsListBalancesV2Response" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "summary": "List merchant balances and whether the returned balance data is confirmed." } }, "/merchant/api/v2/balances/history": { "get": { "operationId": "LedgerMerchants_GetBalanceHistory", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/merchantsGetBalanceHistoryResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "400": { "description": "Invalid balance-history filter or pagination value.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "type": "integer", "format": "int64", "minimum": 0, "maximum": 4294967295, "default": 50, "description": "Page size. Zero or omission defaults to 50; values above 200 are capped to 200." }, { "name": "offset", "in": "query", "required": false, "type": "integer", "format": "int64", "minimum": 0, "maximum": 2147483647, "default": 0, "description": "Zero-based movement offset. Values above 2147483647 are rejected with HTTP 400." }, { "name": "currencyCode", "description": "Optional currency code. Use the value returned by the balance API.", "in": "query", "required": false, "type": "string" }, { "name": "sourceType", "in": "query", "required": false, "type": "string", "enum": [ "payment", "adjustment", "hold", "settlement", "settlement_reversal", "other" ], "description": "Filter by the closed merchant-safe source category returned by this endpoint: payment, adjustment, hold, settlement, settlement_reversal, or other. A settlement reversal corrects a recorded entry without representing a new external transfer. Matching is case-insensitive; values outside this list are rejected with HTTP 400." }, { "name": "sourceId", "in": "query", "required": false, "type": "string", "x-deprecated": true, "description": "Deprecated payment-only correlation filter. Requires sourceType=payment and a valid public payment UUID; other combinations return HTTP 400." }, { "name": "countryCode", "in": "query", "required": false, "type": "string" }, { "name": "scopeType", "description": "Filter by balance scope. Omit the field or use UNSPECIFIED to include all scopes.\n\n - MERCHANT_BALANCE_SCOPE_TYPE_COUNTRY: A country-specific balance identified by currencyCode and an ISO 3166-1 alpha-2 countryCode.\n - MERCHANT_BALANCE_SCOPE_TYPE_GLOBAL: A balance explicitly identified as global, with an empty countryCode.\n - MERCHANT_BALANCE_SCOPE_TYPE_LEGACY_UNSCOPED: A historical balance without a confirmed country. Keep it separate and never infer its country from currency.", "in": "query", "required": false, "type": "string", "enum": [ "MERCHANT_BALANCE_SCOPE_TYPE_UNSPECIFIED", "MERCHANT_BALANCE_SCOPE_TYPE_COUNTRY", "MERCHANT_BALANCE_SCOPE_TYPE_GLOBAL", "MERCHANT_BALANCE_SCOPE_TYPE_LEGACY_UNSCOPED" ], "default": "MERCHANT_BALANCE_SCOPE_TYPE_UNSPECIFIED" } ], "summary": "List merchant-safe balance movements and their authority state." } } }, "definitions": { "commonPageMeta": { "type": "object", "properties": { "limit": { "type": "integer", "format": "int64" }, "offset": { "type": "integer", "format": "int64" }, "totalPages": { "type": "integer", "format": "int64" } }, "title": "Generic pagination metadata for limit/offset pagination" }, "ledgerCustomerSegment": { "type": "string", "enum": [ "CUSTOMER_SEGMENT_UNSPECIFIED", "CUSTOMER_SEGMENT_FTD", "CUSTOMER_SEGMENT_TRUSTED", "CUSTOMER_SEGMENT_VIP" ], "default": "CUSTOMER_SEGMENT_UNSPECIFIED" }, "ledgerPaymentInstruction": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" }, "copyable": { "type": "boolean" } } }, "ledgerPaymentMethod": { "type": "string", "enum": [ "PAYMENT_METHOD_UNSPECIFIED", "PAYMENT_METHOD_CARD", "PAYMENT_METHOD_BANK_ACCOUNT", "PAYMENT_METHOD_BANK_TRANSFER", "PAYMENT_METHOD_MOBILE_MONEY", "PAYMENT_METHOD_MOBILE_MONEY_TRANSFER" ], "default": "PAYMENT_METHOD_UNSPECIFIED", "title": "- PAYMENT_METHOD_CARD: temporary not supported for pay in and payout\n - PAYMENT_METHOD_BANK_ACCOUNT: pay with bank and payout to bank account\navailable for pay in and payout\n - PAYMENT_METHOD_BANK_TRANSFER: available for pay in\n - PAYMENT_METHOD_MOBILE_MONEY: available for pay in and payout\n - PAYMENT_METHOD_MOBILE_MONEY_TRANSFER: customer-initiated mobile money transfer; available for pay in" }, "ledgerPaymentOrder": { "type": "object", "properties": { "id": { "type": "string", "title": "Payment order ID (UUID, uniquely generated by the system)" }, "merchantReference": { "type": "string", "description": "Merchant reference.\nUnique reference of the payment order in the merchant's system. Will be passed back to the merchant in the webhooks." }, "paymentMethod": { "$ref": "#/definitions/ledgerPaymentMethod", "title": "Method of the payment order" }, "type": { "$ref": "#/definitions/ledgerPaymentOrderType", "title": "Type of payment order" }, "status": { "$ref": "#/definitions/ledgerPaymentOrderStatus", "title": "Current status of the payment order" }, "amount": { "type": "string", "format": "int64", "description": "Requested amount of the payment order in minor units. For pay-ins, this is\nthe full amount the customer is expected to pay. It does not change after\nthe payment is created." }, "currencyCode": { "type": "string", "title": "Currency code of the payment order" }, "currencyMinorUnits": { "type": "integer", "format": "int32", "x-nullable": true, "description": "Currency minor units captured at payment creation time.\nOptional so zero-minor currencies such as UGX/XAF/XOF are distinguishable\nfrom an unknown or unset value." }, "paymentUrl": { "type": "string", "title": "paymentUrl is the page where the customer continues payment; redirectUrl is your saved return URL. Neither confirms completion. Use payment status or a verified webhook to confirm the result." }, "redirectUrl": { "type": "string", "title": "paymentUrl is the page where the customer continues payment; redirectUrl is your saved return URL. Neither confirms completion. Use payment status or a verified webhook to confirm the result." }, "failureReason": { "type": "string", "title": "Reason for the failure of the payment order. Known public availability\nreason: method_unavailable, shown as \"Payment method is temporarily\nunavailable. Please contact support.\"" }, "failureReasonCode": { "type": "string", "format": "int64", "title": "Error code for the failure of the payment order" }, "createdAt": { "type": "string", "format": "date-time", "title": "Timestamp when the payment order was created" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Timestamp when the payment order was last updated" }, "trafficVertical": { "$ref": "#/definitions/ledgerTrafficVertical", "title": "Transaction vertical classification" }, "customerSegment": { "$ref": "#/definitions/ledgerCustomerSegment", "title": "Customer lifecycle segment" }, "bankTransferDetails": { "$ref": "#/definitions/ledgerPaymentOrderBankTransferDetails", "description": "Generated bank-transfer account details and current availability state.\nReturned on hosted-checkout and merchant payment-order responses when available." }, "mobileMoneyTransferDetails": { "$ref": "#/definitions/ledgerPaymentOrderMobileMoneyTransferDetails", "description": "Transfer instructions and their availability for this mobile-money-transfer payment. Instructions can arrive after creation in a PENDING-to-PENDING webhook; inspect the details and updatedAt, not only financial status. Deduplicate webhook deliveries by Idempotency-Key. While processing, read the payment with bounded backoff or consume merchant webhooks; honor retryAfter when supplied. Do not repeat create to obtain instructions. Actionable details are omitted for terminal payments." }, "paymentSubMethod": { "type": "string", "description": "Public submethod code selected for the payment, when present.\nCurrent value: moniepoint for bank transfer." }, "actualAmount": { "type": "string", "format": "int64", "description": "Gross payment amount in minor units that Transcore recognizes for the payment.\nIt is returned for every payment, including when it equals the requested\namount. For pay-ins, credit the customer only when status is\nPAYMENT_ORDER_STATUS_COMPLETED and apply that credit idempotently per\npayment ID across reads and webhooks. For payouts, use this amount for\npayout reconciliation, not another customer credit.\nIt is not a completion signal by itself.\nHistorical payments completed before actual-amount tracking retain the\nrequested amount here; this does not confirm an additional payment. Do not use\nhistorical reads to initiate new customer credits.\nFees are accounted separately and do not change this value. The recorded value can remain present after a later status correction.\nAlways reconcile it with the latest payment status. JSON transports\nreturn this int64 as a base-10 digit string." } }, "title": "Payment order of any type" }, "ledgerPaymentOrderBankTransferDetails": { "type": "object", "properties": { "generationStatus": { "type": "string", "description": "Public generation status: pending, processing, succeeded, failed_retryable, or failed_manual_review." }, "accountName": { "type": "string", "description": "Generated virtual account name. Present only when generation_status is succeeded." }, "accountNumber": { "type": "string", "description": "Generated virtual account number. Present only when generation_status is succeeded." }, "expiresAt": { "type": "string", "format": "date-time", "x-nullable": true, "description": "Expiration time for the generated virtual account, when supplied." }, "bankName": { "type": "string", "description": "Generated virtual account bank name, when supplied." }, "failureReason": { "type": "string", "description": "Public failure reason when payment instructions are unavailable." }, "retryAfter": { "type": "string", "format": "date-time", "x-nullable": true, "description": "Earliest retry/poll time for retryable processing or failed states." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update for the generation state." } } }, "ledgerPaymentOrderMobileMoneyTransferDetails": { "type": "object", "properties": { "generationStatus": { "type": "string", "description": "Public generation status: pending, processing, succeeded, failed_retryable, or failed_manual_review." }, "instructions": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/ledgerPaymentInstruction" }, "description": "Structured transfer instructions. Render these fields directly; do not parse displayMessage for requisites." }, "expiresAt": { "type": "string", "format": "date-time", "x-nullable": true, "description": "Expiration time for the generated transfer instructions, when supplied." }, "displayMessage": { "type": "string", "description": "Display text only; its presence does not mean transfer instructions are ready. Use instructions and generationStatus to determine availability." }, "failureReason": { "type": "string", "description": "Public failure reason when payment instructions are unavailable." }, "retryAfter": { "type": "string", "format": "date-time", "x-nullable": true, "description": "Earliest retry/poll time for retryable processing or failed states." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update for the generation state." } }, "description": "Customer-displayable mobile-money-transfer instructions, shared by payment readback and merchant webhooks." }, "ledgerPaymentOrderStatus": { "type": "string", "enum": [ "PAYMENT_ORDER_STATUS_UNSPECIFIED", "PAYMENT_ORDER_STATUS_CREATED", "PAYMENT_ORDER_STATUS_PENDING", "PAYMENT_ORDER_STATUS_COMPLETED", "PAYMENT_ORDER_STATUS_CANCELLED", "PAYMENT_ORDER_STATUS_EXPIRED", "PAYMENT_ORDER_STATUS_FAILED" ], "default": "PAYMENT_ORDER_STATUS_UNSPECIFIED", "title": "- PAYMENT_ORDER_STATUS_CREATED: Payment order is created\n - PAYMENT_ORDER_STATUS_PENDING: Payment order is being processed\n - PAYMENT_ORDER_STATUS_COMPLETED: Payment order is completed\n - PAYMENT_ORDER_STATUS_CANCELLED: Payment order is cancelled\n - PAYMENT_ORDER_STATUS_EXPIRED: Payment order is expired\n - PAYMENT_ORDER_STATUS_FAILED: Payment order is failed" }, "ledgerPaymentOrderType": { "type": "string", "enum": [ "PAYMENT_ORDER_TYPE_UNSPECIFIED", "PAYMENT_ORDER_TYPE_PAYMENT_IN", "PAYMENT_ORDER_TYPE_PAYMENT_OUT" ], "default": "PAYMENT_ORDER_TYPE_UNSPECIFIED", "title": "- PAYMENT_ORDER_TYPE_PAYMENT_IN: Payment order is for a pay-in\n - PAYMENT_ORDER_TYPE_PAYMENT_OUT: Payment order is for a pay-out" }, "ledgerTrafficVertical": { "type": "string", "enum": [ "TRAFFIC_VERTICAL_UNSPECIFIED", "TRAFFIC_VERTICAL_GAMBLING", "TRAFFIC_VERTICAL_FOREX", "TRAFFIC_VERTICAL_OTHER" ], "default": "TRAFFIC_VERTICAL_UNSPECIFIED" }, "merchantsAuthorizeOtpRequest": { "type": "object", "properties": { "paymentOrderId": { "type": "string" }, "token": { "type": "string" } } }, "merchantsAuthorizeOtpResponse": { "type": "object", "properties": { "isAuthorized": { "type": "boolean" }, "isStkPromptRequired": { "type": "boolean" }, "displayMessage": { "type": "string", "description": "Optional customer-facing guidance. Display it as plain text only for a flow whose copy you have reviewed. Never parse it as payment status or a failure reason." } } }, "merchantsBank": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "merchantsCreatePayInOrderRequest": { "type": "object", "properties": { "amount": { "type": "string", "format": "int64", "title": "Amount of the payment order in minor units", "description": "Send amount in integer minor units as a digit-only JSON string or an integer JSON number; this is the only portable representation. Decimal points and exponent notation are not portable and may be rejected. Payment-creation request bodies have a supported maximum of 1 MiB; implementations may return HTTP 413 for larger bodies." }, "currencyCode": { "type": "string", "description": "ISO 4217 currency code of the payment order, for example NGN, KES, GMD, MWK." }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code of the payment market, for example NG, KE, GM, MW.\nRequired for every payment request; it is never inferred from currency or payment method." }, "paymentMethod": { "$ref": "#/definitions/ledgerPaymentMethod", "title": "Method of the payment order" }, "paymentSubMethod": { "type": "string", "description": "Optional public submethod code. Supported only for PAYMENT_METHOD_BANK_TRANSFER;\ncurrently supported value: moniepoint. Omit for other payment methods." }, "merchantReference": { "type": "string", "description": "Merchant reference\nUnique reference of the payment order in the merchant's system. Will be passed back to the merchant in the webhooks." }, "redirectUrl": { "type": "string", "title": "Customer return URL. A return does not confirm payment completion." }, "isGambling": { "type": "boolean", "title": "Indicates whether the transaction is related to gambling" }, "trafficVertical": { "$ref": "#/definitions/ledgerTrafficVertical", "description": "Vertical of merchant traffic. If omitted, the account-compatible fallback is used." }, "customerSegment": { "$ref": "#/definitions/ledgerCustomerSegment", "description": "Customer segment. If omitted/unspecified, FTD is used." }, "bankAccountDetails": { "$ref": "#/definitions/merchantsPayInBankAccountRequestDetails" }, "bankTransferDetails": { "$ref": "#/definitions/merchantsPayInBankTransferRequestDetails" }, "mobileMoneyDetails": { "$ref": "#/definitions/merchantsPayInMobileMoneyRequestDetails" }, "mobileMoneyTransferDetails": { "$ref": "#/definitions/merchantsPayInMobileMoneyTransferRequestDetails" }, "cardDetails": { "$ref": "#/definitions/merchantsPayInCardRequestDetails" } } }, "merchantsCreatePayInOrderResponse": { "type": "object", "properties": { "paymentOrder": { "$ref": "#/definitions/ledgerPaymentOrder" }, "bankAccountDetails": { "$ref": "#/definitions/merchantsPayInBankAccountResponseDetails" }, "bankTransferDetails": { "$ref": "#/definitions/merchantsPayInBankTransferResponseDetails" }, "mobileMoneyDetails": { "$ref": "#/definitions/merchantsPayInMobileMoneyResponseDetails" }, "mobileMoneyTransferDetails": { "$ref": "#/definitions/merchantsPayInMobileMoneyTransferResponseDetails" } } }, "merchantsCreatePayOutOrderRequest": { "type": "object", "properties": { "amount": { "type": "string", "format": "int64", "title": "Amount of the payment order in minor units", "description": "Send amount in integer minor units as a digit-only JSON string or an integer JSON number; this is the only portable representation. Decimal points and exponent notation are not portable and may be rejected. Payment-creation request bodies have a supported maximum of 1 MiB; implementations may return HTTP 413 for larger bodies." }, "currencyCode": { "type": "string", "description": "ISO 4217 currency code of the payment order, for example NGN, KES, GMD, MWK." }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code of the payment market, for example NG, KE, GM, MW.\nRequired for every payment request; it is never inferred from currency or payment method." }, "paymentMethod": { "$ref": "#/definitions/ledgerPaymentMethod", "title": "Method of the payment order" }, "merchantReference": { "type": "string", "description": "Merchant reference\nUnique reference of the payment order in the merchant's system. Will be passed back to the merchant in the webhooks." }, "isGambling": { "type": "boolean", "title": "Indicates whether the transaction is related to gambling" }, "trafficVertical": { "$ref": "#/definitions/ledgerTrafficVertical", "description": "Vertical of merchant traffic. If omitted, the account-compatible fallback is used." }, "customerSegment": { "$ref": "#/definitions/ledgerCustomerSegment", "description": "Customer segment. If omitted/unspecified, FTD is used." }, "bankAccountDetails": { "$ref": "#/definitions/merchantsPayOutBankAccountRequestDetails" }, "mobileMoneyDetails": { "$ref": "#/definitions/merchantsPayOutMobileMoneyRequestDetails" } } }, "merchantsCreatePayOutOrderResponse": { "type": "object", "properties": { "paymentOrder": { "$ref": "#/definitions/ledgerPaymentOrder" } } }, "merchantsGetBalanceHistoryResponse": { "type": "object", "properties": { "movements": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/merchantsMerchantBalanceMovement" } }, "page": { "$ref": "#/definitions/merchantsMerchantBalancePageMeta" }, "authorityState": { "$ref": "#/definitions/merchantsMerchantBalanceAuthorityState" } }, "required": [ "movements", "page", "authorityState" ] }, "merchantsGetMarketCatalogResponse": { "type": "object", "properties": { "markets": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/merchantsMarketCatalogMarket" } } } }, "merchantsInitializePayInRequest": { "type": "object", "properties": { "amount": { "type": "string", "format": "int64", "title": "Amount of the payment order in minor units", "description": "Send amount in integer minor units as a digit-only JSON string or an integer JSON number; this is the only portable representation. Decimal points and exponent notation are not portable and may be rejected. Payment-creation request bodies have a supported maximum of 1 MiB; implementations may return HTTP 413 for larger bodies." }, "currencyCode": { "type": "string", "description": "ISO 4217 currency code of the payment order, for example NGN, KES, GMD, MWK." }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code of the payment market, for example NG, KE, GM, MW.\nRequired for every payment request; it is never inferred from currency or payment method." }, "paymentSubMethod": { "type": "string", "description": "Optional public submethod code. Supported only for PAYMENT_METHOD_BANK_TRANSFER;\ncurrently supported value: moniepoint. Omit for other payment methods." }, "paymentMethod": { "$ref": "#/definitions/ledgerPaymentMethod", "title": "Method of the payment order" }, "merchantReference": { "type": "string", "description": "Merchant reference\nUnique reference of the payment order in the merchant's system. Will be passed back to the merchant in the webhooks." }, "redirectUrl": { "type": "string", "title": "Customer return URL. A return does not confirm payment completion." }, "isGambling": { "type": "boolean", "title": "Indicates whether the transaction is related to gambling" }, "trafficVertical": { "$ref": "#/definitions/ledgerTrafficVertical", "description": "Vertical of merchant traffic. If omitted, the account-compatible fallback is used." }, "customerSegment": { "$ref": "#/definitions/ledgerCustomerSegment", "description": "Customer segment. If omitted/unspecified, FTD is used." }, "mobileMoneyOperator": { "type": "string", "description": "Mobile money operator or transfer rail code for hosted-checkout initialization. For PAYMENT_METHOD_MOBILE_MONEY, send an approved public CAPS code returned by ListPayInMMO, such as MPESA, TELECEL, MTN, or ORANGE, when the selected market requires one; otherwise omit it. Treat discovery codes as opaque and reuse them exactly. Required for PAYMENT_METHOD_MOBILE_MONEY_TRANSFER; use ListPayInMMO to retrieve valid transfer rail codes such as ORANGE or MTN." } } }, "merchantsInitializePayInResponse": { "type": "object", "properties": { "paymentOrder": { "$ref": "#/definitions/ledgerPaymentOrder" }, "expiresAt": { "type": "string", "format": "date-time", "title": "Expiration time in UTC. The payment can be processed only before this time" } } }, "merchantsListBalancesV2Response": { "type": "object", "properties": { "balances": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/merchantsMerchantBalanceV2" } }, "authorityState": { "$ref": "#/definitions/merchantsMerchantBalanceAuthorityState" } }, "required": [ "balances", "authorityState" ] }, "merchantsListPayInBanksResponse": { "type": "object", "properties": { "banks": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/merchantsBank" } } } }, "merchantsListPayInMMOResponse": { "type": "object", "properties": { "operators": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/merchantsMobileMoneyOperator" } } } }, "merchantsListPayOutBanksResponse": { "type": "object", "properties": { "banks": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/merchantsBank" } } } }, "merchantsListPayOutMMOResponse": { "type": "object", "properties": { "operators": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/merchantsMobileMoneyOperator" } } } }, "merchantsMarketCatalogMarket": { "type": "object", "properties": { "countryCode": { "type": "string" }, "currencyCode": { "type": "string" }, "methodsIn": { "type": "array", "items": { "type": "string" } }, "methodsOut": { "type": "array", "items": { "type": "string" } } } }, "merchantsMerchantBalanceAuthorityState": { "type": "string", "enum": [ "MERCHANT_BALANCE_AUTHORITY_STATE_UNSPECIFIED", "MERCHANT_BALANCE_AUTHORITY_STATE_UNAVAILABLE", "MERCHANT_BALANCE_AUTHORITY_STATE_BACKFILLING", "MERCHANT_BALANCE_AUTHORITY_STATE_CATCHING_UP", "MERCHANT_BALANCE_AUTHORITY_STATE_AUTHORITATIVE" ], "default": "MERCHANT_BALANCE_AUTHORITY_STATE_UNSPECIFIED", "description": " - MERCHANT_BALANCE_AUTHORITY_STATE_UNAVAILABLE: Confirmed balance information is not yet available for this account. This state does not by itself disable payment processing; the payout response decides acceptance.\n - MERCHANT_BALANCE_AUTHORITY_STATE_BACKFILLING: Balance information is being prepared and is not yet confirmed.\n - MERCHANT_BALANCE_AUTHORITY_STATE_CATCHING_UP: Recent balance changes are being included; the returned information is not yet confirmed.\n - MERCHANT_BALANCE_AUTHORITY_STATE_AUTHORITATIVE: The returned balances and history are confirmed for this account." }, "merchantsMerchantBalanceMovement": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque public movement identifier." }, "operationId": { "type": "string", "description": "Deprecated opaque grouping handle retained for V2 compatibility. Do not use it as a payment identifier.", "x-deprecated": true }, "currencyCode": { "type": "string", "description": "Currency code for this balance movement." }, "bucket": { "type": "string" }, "direction": { "type": "string" }, "amountMinor": { "type": "string", "format": "int64" }, "balanceBeforeMinor": { "type": "string", "format": "int64", "x-nullable": true }, "balanceAfterMinor": { "type": "string", "format": "int64", "x-nullable": true }, "sourceType": { "type": "string", "description": "Closed merchant-safe type: payment, adjustment, hold, settlement,\nsettlement_reversal, or other. A settlement reversal corrects a recorded\nsettlement entry; it does not represent a new external transfer.", "enum": [ "payment", "adjustment", "hold", "settlement", "settlement_reversal", "other" ] }, "sourceId": { "type": "string", "description": "Deprecated payment correlation handle. Equal to the public payment ID for verified payment movements; empty otherwise.", "x-deprecated": true }, "sourceReference": { "type": "string", "description": "Merchant-owned payment reference for payment movements; empty for other movement types." }, "description": { "type": "string", "description": "Description of the movement for your reconciliation." }, "createdAt": { "type": "string", "format": "date-time" }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code for COUNTRY scope; an empty string for GLOBAL or LEGACY_UNSCOPED." }, "scopeType": { "$ref": "#/definitions/merchantsMerchantBalanceScopeType" }, "minorUnit": { "type": "integer", "format": "int64" } }, "required": [ "id", "operationId", "currencyCode", "bucket", "direction", "amountMinor", "sourceType", "sourceId", "sourceReference", "description", "createdAt", "countryCode", "scopeType", "minorUnit" ] }, "merchantsMerchantBalanceScopeType": { "type": "string", "enum": [ "MERCHANT_BALANCE_SCOPE_TYPE_UNSPECIFIED", "MERCHANT_BALANCE_SCOPE_TYPE_COUNTRY", "MERCHANT_BALANCE_SCOPE_TYPE_GLOBAL", "MERCHANT_BALANCE_SCOPE_TYPE_LEGACY_UNSCOPED" ], "default": "MERCHANT_BALANCE_SCOPE_TYPE_UNSPECIFIED", "description": " - MERCHANT_BALANCE_SCOPE_TYPE_COUNTRY: A country-specific balance identified by currencyCode and an ISO 3166-1 alpha-2 countryCode.\n - MERCHANT_BALANCE_SCOPE_TYPE_GLOBAL: A balance explicitly identified as global, with an empty countryCode.\n - MERCHANT_BALANCE_SCOPE_TYPE_LEGACY_UNSCOPED: A historical balance without a confirmed country. Keep it separate and never infer its country from currency." }, "merchantsMerchantBalanceV2": { "type": "object", "properties": { "currencyCode": { "type": "string", "description": "Currency code. Combine it with countryCode and scopeType to identify the balance." }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code for COUNTRY scope; an empty string for GLOBAL or LEGACY_UNSCOPED." }, "scopeType": { "$ref": "#/definitions/merchantsMerchantBalanceScopeType" }, "minorUnit": { "type": "integer", "format": "int64", "description": "Currency exponent used by every *Minor amount. Divide by 10^minorUnit only for display." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp of this balance position revision." }, "availableMinor": { "type": "string", "format": "int64" }, "pendingMinor": { "type": "string", "format": "int64" }, "pendingInMinor": { "type": "string", "format": "int64" }, "pendingOutMinor": { "type": "string", "format": "int64" }, "holdMinor": { "type": "string", "format": "int64" }, "currentMinor": { "type": "string", "format": "int64" }, "payoutAvailableMinor": { "type": "string", "format": "int64" }, "payoutControlsRevision": { "type": "integer", "format": "int32", "description": "Revision of the effective payout controls. Zero means default controls; it changes independently of version." }, "version": { "type": "integer", "format": "int32", "description": "Revision of this balance position. It changes independently of payoutControlsRevision; do not calculate it client-side." }, "authorityState": { "$ref": "#/definitions/merchantsMerchantBalanceAuthorityState" } }, "required": [ "currencyCode", "countryCode", "scopeType", "minorUnit", "updatedAt", "availableMinor", "pendingMinor", "pendingInMinor", "pendingOutMinor", "holdMinor", "currentMinor", "payoutAvailableMinor", "payoutControlsRevision", "version", "authorityState" ] }, "merchantsMobileMoneyOperator": { "type": "object", "properties": { "operator": { "type": "string", "description": "Approved public CAPS operator code matching [A-Z0-9_]+. Treat it as opaque and reuse the value returned by discovery." }, "name": { "type": "string", "description": "Human-readable mobile money operator name for display in merchant UI." } } }, "merchantsPayInBankAccountRequestDetails": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "bankCode": { "type": "string" } } }, "merchantsPayInBankAccountResponseDetails": { "type": "object", "properties": { "redirectUrl": { "type": "string", "title": "The redirect url to proceed with payment" } } }, "merchantsPayInBankTransferRequestDetails": { "type": "object", "properties": { "email": { "type": "string" } } }, "merchantsPayInBankTransferResponseDetails": { "type": "object", "properties": { "accountName": { "type": "string" }, "accountNumber": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time", "x-nullable": true, "description": "Expiration time in UTC." }, "bankName": { "type": "string", "description": "Bank or financial institution name for the generated transfer account." } } }, "merchantsPayInCardRequestDetails": { "type": "object", "properties": { "email": { "type": "string" } } }, "merchantsPayInMobileMoneyRequestDetails": { "type": "object", "properties": { "email": { "type": "string" }, "mobileNumber": { "type": "string", "description": "Customer mobile wallet number / MSISDN in the accepted format." }, "operator": { "type": "string", "description": "Approved public mobile money operator code for the customer wallet.\nUse a CAPS code returned by ListPayInMMO, for example MPESA, TELECEL, MTN, or ORANGE.\nTreat the returned code as opaque and reuse it exactly." }, "voucherPin": { "type": "string", "description": "Voucher PIN for voucher-based mobile money markets, for example Botswana BWP with public operator OTT_VOUCHER." } } }, "merchantsPayInMobileMoneyResponseDetails": { "type": "object", "properties": { "isOtpAuthRequired": { "type": "boolean", "description": "Continuation signal. A true value does not by itself confirm that OTP authorization applies to the payment. Follow the documented continuation flow for the selected market and payment method." }, "displayMessage": { "type": "string", "description": "Optional customer-facing guidance. Display it as plain text only for a flow whose copy you have reviewed.\nNever parse it as payment status, a failure reason, or payment instructions.\nThe message, or mobile_money_details itself, may be absent while a pending payment is reconciled\nand no customer action is known.\nThis field is returned only by create/process responses; later payment-order reads do not\ncontain mobile_money_details. Clients that need to keep showing the guidance must retain it." } } }, "merchantsPayInMobileMoneyTransferRequestDetails": { "type": "object", "properties": { "operator": { "type": "string", "description": "Mobile-money-transfer rail selector used to choose the requested transfer route; for example ORANGE or MTN.\nThis is not the customer wallet operator and does not set the payment's mobile-money operator selection.\nUse ListPayInMMO to retrieve valid values." }, "mobileNumber": { "type": "string", "description": "mobileNumber public field: customer mobile wallet number / MSISDN for mobile-money-transfer pay-ins." } } }, "merchantsPayInMobileMoneyTransferResponseDetails": { "type": "object", "properties": { "instructions": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/merchantsPayInPaymentInstruction" } }, "expiresAt": { "type": "string", "format": "date-time", "x-nullable": true }, "displayMessage": { "type": "string", "description": "Display text only; a response without instructions acknowledges processing. Read the payment for instruction availability before showing transfer details." } } }, "merchantsPayInPaymentInstruction": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" }, "copyable": { "type": "boolean" } } }, "merchantsPayOutBankAccountRequestDetails": { "type": "object", "properties": { "email": { "type": "string" }, "bankCode": { "type": "string" }, "account": { "type": "string" }, "name": { "type": "string", "description": "Beneficiary account holder name.\nSupply the name unless omission is explicitly supported for your configured payout path." } } }, "merchantsPayOutMobileMoneyRequestDetails": { "type": "object", "properties": { "email": { "type": "string" }, "operator": { "type": "string", "description": "Approved public mobile money operator code of the beneficiary wallet.\nUse a CAPS code returned by ListPayOutMMO, for example MPESA, TELECEL, MTN, or ORANGE.\nTreat the returned code as opaque and reuse it exactly." }, "mobileNumber": { "type": "string", "description": "Beneficiary mobile wallet number / MSISDN in the accepted format." }, "accountName": { "type": "string", "description": "Beneficiary account name.\nSupply the name unless omission is explicitly supported for your configured payout path." } } }, "protobufAny": { "type": "object", "properties": { "@type": { "type": "string" } }, "additionalProperties": {} }, "rpcStatus": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/protobufAny" } } } }, "merchantsMerchantBalancePageMeta": { "type": "object", "properties": { "limit": { "type": "integer", "format": "int64" }, "offset": { "type": "integer", "format": "int64" }, "totalPages": { "type": "integer", "format": "int64" } }, "title": "Generic pagination metadata for limit/offset pagination", "required": [ "limit", "offset", "totalPages" ] } }, "host": "merchants-api.tcpay.io", "basePath": "/", "schemes": [ "https" ], "securityDefinitions": { "Bearer": { "type": "apiKey", "name": "Authorization", "in": "header", "description": "Enter your bearer token in the format: Bearer {token}" } }, "security": [ { "Bearer": [] } ] }