> ## Documentation Index > Fetch the complete documentation index at: https://docs.boomfi.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Get Payment > Get a payment by id. The payload matches the merchant webhook payment document, including nested customer, plan, invoice, and on-chain transactions when present. paid_amount is the on-chain amount received, capped at amount, and is omitted until a deposit is observed. When status is RequiresAction, next_action is a machine-readable code. Codes that carry content append it after the first colon; codes without content have no colon. ## OpenAPI ````yaml /openapi.yaml get /payments/{paymentId} openapi: 3.1.0 info: contact: email: support@boomfi.xyz name: API Support description: >- The BoomFi Merchants API provides a set of endpoints for merchants to manage their accounts, transactions, and more. Hosts differ per brand/environment; use the brand-specific base URL from the docs. title: BoomFi Merchants API version: '1.0' servers: - url: https://mapi.boomfi.xyz/v1 description: Production - url: https://mapi-test.boomfi.xyz/v1 description: Test security: [] tags: - description: Payment links name: Paylinks - description: Billing plans name: Plans - description: Subscriptions name: Subscriptions - description: Customer records name: Customers - description: Invoices name: Invoices - description: Payments name: Payments - description: Organisation events name: Events - description: Organisation profile and display settings name: Organisation - description: Webhook and request-signing secrets name: Secrets - description: Settlement accounts name: Accounts - name: External Accounts - description: Managed virtual accounts, balances, pay-in, and payout name: Virtual Accounts - description: Partner-managed accounts, virtual accounts, pay-in, and payout name: Partners - description: Partner maintain-balance automations name: Partner Balance Monitoring - name: Checkout Sessions paths: /payments/{paymentId}: get: tags: - Payments summary: Get Payment description: >- Get a payment by id. The payload matches the merchant webhook payment document, including nested customer, plan, invoice, and on-chain transactions when present. paid_amount is the on-chain amount received, capped at amount, and is omitted until a deposit is observed. When status is RequiresAction, next_action is a machine-readable code. Codes that carry content append it after the first colon; codes without content have no colon. parameters: - description: Unique payment identifier (pay_... or raw UUID) example: pay_01HXYZ in: path name: paymentId required: true schema: type: string - description: >- Target sub-merchant organisation ID. Required for partner-delegated requests, which must be signed with the partner secret. in: header name: X-ORG-ID schema: type: string responses: '200': description: OK content: application/json: schema: $ref: >- #/components/schemas/internal.Response-payments_MerchantPaymentDocument '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/internal.ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/internal.ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/internal.ErrorResponse' security: - ApiKeyAuth: [] components: schemas: internal.Response-payments_MerchantPaymentDocument: properties: data: allOf: - $ref: '#/components/schemas/payments.MerchantPaymentDocument' description: Response payload when the request succeeded. error: description: True when the request failed. type: boolean message: description: Human-readable status or error message. type: string type: object internal.ErrorResponse: properties: error: allOf: - $ref: '#/components/schemas/internal.ErrorStruct' description: Error details including HTTP-style code and message. type: object payments.MerchantPaymentDocument: properties: amount: description: Amount as a decimal string in major units. example: '25.00' type: string amount_usd: description: Amount denominated in USD. example: '25.00' type: string automation: additionalProperties: {} description: >- Payout automation payload, when this payment is a payout and one is stored. type: object cf_headers: additionalProperties: type: string description: >- Cloudflare or edge request headers captured with the payment, when present. type: object chain_id: description: Blockchain chain ID for the pay-in, when known. example: 8453 type: integer created_at: description: When the payment was created (RFC3339). example: '2024-06-15T14:32:10.000Z' type: string crypto_transaction: allOf: - $ref: '#/components/schemas/models.PublicCryptoTransaction' description: Primary crypto transaction associated with this payment. crypto_transactions: description: >- All pay-in (or refund) crypto transactions when more than one exists. items: $ref: '#/components/schemas/models.PublicCryptoTransaction' type: array currency: description: Currency symbol (for example USDC or USD). example: USDC type: string customer: allOf: - $ref: '#/components/schemas/payments.MerchantPaymentCustomer' description: >- Customer associated with this payment. Omitted for Deposit and Payout. customer_id: description: Customer ID linked to this payment (cus_...). example: cus_01HXYZ type: string description: description: Description copied from payment properties, when set. type: string error: additionalProperties: {} description: Payout error details, when this payout failed. type: object from_account: allOf: - $ref: '#/components/schemas/models.PublicOrgSettlementAccount' description: Source settlement account for a deposit or payout. id: description: Unique payment identifier (pay_...). example: pay_01HXYZ type: string invoice: allOf: - $ref: '#/components/schemas/payments.MerchantPaymentInvoice' description: Invoice linked to this payment, when one exists. invoice_id: description: Invoice ID linked to this payment. example: inv_01HXYZ type: string metadata: additionalProperties: {} description: Arbitrary merchant-defined metadata. type: object next_action: description: >- Next client action required to continue the flow. The value contains a machine-readable code, followed by a colon and the action content. example: travel_rule:https://example.com/travel-rule/... type: string org: allOf: - $ref: '#/components/schemas/payments.MerchantPaymentOrg' description: Public organisation info attached to the document. org_id: description: Organisation ID that owns this payment (org_...). example: org_01HXYZ type: string paid_amount: description: >- On-chain amount received, capped at amount. Omitted until a deposit is observed. example: '10.00' type: string parent_id: description: >- Identifier of the parent payment, when this row is nested (for example a refund). type: string payment_link: allOf: - $ref: '#/components/schemas/payments.MerchantPaymentPaylink' description: Payment link associated with this payment (v1 legacy overlay). payment_method: allOf: - $ref: '#/components/schemas/docenums.PaymentMethod' description: Payment method used for this payment. example: ProxyWallet payout_splits: description: >- How payment proceeds were split to destination addresses (deposit/payout). items: $ref: '#/components/schemas/models.PublicPayoutSplit' type: array plan: allOf: - $ref: '#/components/schemas/payments.MerchantPaymentPlan' description: >- Plan associated with this payment, with subscription/invoice overrides applied. plan_currency: description: >- Currency the payment was billed in, with paylink variant overrides applied. example: USD type: string plan_price: description: >- Amount billed in PlanCurrency, with paylink variant overrides applied. Per unit, and not adjusted by later edits to the plan. Omitted when unknown. example: '25.00' type: string properties: allOf: - $ref: '#/components/schemas/payments.MerchantPaymentProperties' description: Merchant-safe payment properties (internal keys stripped). ramp: allOf: - $ref: '#/components/schemas/payments.MerchantPaymentRamp' description: Off-ramp memo, when present. reference: description: Merchant-defined reference string. example: order-10042 type: string refund_amount: description: Refund amount as a decimal string, when this payment is a refund. type: string refund_recipient_address: description: Address that received a crypto refund. type: string refunded_plan: allOf: - $ref: '#/components/schemas/payments.MerchantPaymentRefundedPlan' description: Refunded plan identifiers, when this payment is a refund. scheduled_time: description: >- Scheduled run time as a unix timestamp, when the payment is scheduled. type: integer sender_address: description: On-chain address that originated a deposit or payout. type: string settlement_address: description: Settlement destination address, when present on a succeeded payment. example: 0xdemo222222222222222222222222222222222222 type: string settlement_amount: description: Settled amount as a decimal string, when present. example: '24.50' type: string settlement_from_address: description: Address that sent the settlement transaction, when present. type: string settlement_transaction: allOf: - $ref: '#/components/schemas/models.PublicCryptoTransaction' description: >- Settlement crypto transaction, when the payment has succeeded and settled. source: allOf: - $ref: '#/components/schemas/docenums.BillingSource' description: Origin system or integration that created this payment. example: BoomFi status: allOf: - $ref: '#/components/schemas/docenums.PaymentStatus' description: Status of this payment. example: RequiresAction to_account: allOf: - $ref: '#/components/schemas/models.PublicOrgSettlementAccount' description: Destination settlement account for a deposit or payout. to_address: description: Destination address for a payout. type: string updated_at: description: When the payment was last updated (RFC3339). example: '2024-06-15T14:33:01.000Z' type: string type: object internal.ErrorStruct: properties: code: description: |- Error code Example: 400 example: 400 type: integer errors: description: List of errors items: $ref: '#/components/schemas/internal.SingleError' type: array message: description: |- Error message Example: Insufficient quantity example: Insufficient quantity type: string type: object models.PublicCryptoTransaction: properties: chain_id: description: Blockchain chain ID. example: 8453 type: integer created_at: description: When the resource was created (RFC3339). example: '2024-06-15T14:32:40.000Z' type: string payment_id: description: Unique identifier of the payment linked to this resource. example: pay_01HXYZ type: string status: allOf: - $ref: '#/components/schemas/docenums.TransactionStatus' description: Status of this resource. example: Success transaction_hash: description: On-chain transaction hash. example: 0xdemoaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa type: string type: allOf: - $ref: '#/components/schemas/docenums.TransactionType' description: Resource or value type. example: Payment updated_at: description: When the resource was last updated (RFC3339). example: '2024-06-15T14:32:45.000Z' type: string type: object payments.MerchantPaymentCustomer: properties: created_at: description: When the customer was created (RFC3339). example: '2024-06-01T09:00:00.000Z' type: string deleted_at: description: When the customer was soft-deleted (RFC3339), if applicable. type: string email: description: Customer email address. example: ada@example.com type: string id: description: Customer display ID (cus_...). example: cus_01HXYZ type: string metadata: additionalProperties: {} description: Arbitrary merchant-defined metadata. type: object name: description: Customer display name. example: Ada Lovelace type: string org_id: description: Organisation display ID (org_...). example: org_01HXYZ type: string phone: description: Customer phone number. example: '+15555550100' type: string properties: additionalProperties: {} description: Internal properties (for example social handles). type: object reference: description: Merchant-defined customer reference. example: ada-001 type: string updated_at: description: When the customer was last updated (RFC3339). example: '2024-06-15T14:32:10.000Z' type: string wallet_address: description: Blockchain wallet address associated with the customer. example: 0xdemo111111111111111111111111111111111111 type: string type: object models.PublicOrgSettlementAccount: properties: account_type: description: Account type. enum: - CryptoPayIn - CryptoPayOut - FiatPayIn - FiatPayOut - Virtual - ProxyWallet - GasMaster - Crypto - Bank - Card - MPCVault - GooglePay - ApplePay type: string address: description: >- On-chain wallet address or postal street address, depending on context. type: string chain_id: description: Blockchain chain ID. type: integer currencies: description: Supported currency codes for this account or chain. items: type: string type: array enabled: description: Whether this resource is enabled. type: boolean id: description: Unique resource identifier. type: integer name: description: Display name. type: string reference: description: Merchant-defined reference string. type: string type: object payments.MerchantPaymentInvoice: properties: amount: description: Amount as a decimal string in major units. example: '25.00' type: string created_at: description: When the invoice was created (RFC3339). example: '2024-06-15T14:32:10.000Z' type: string currency: description: Currency symbol (for example USDC or USD). example: USDC type: string customer_id: description: Customer ID linked to this invoice. example: cus_01HXYZ type: string due_at: description: When payment is due (RFC3339). example: '2024-06-15T14:32:10.000Z' type: string dunning_status: allOf: - $ref: '#/components/schemas/docenums.DunningStatus' description: Dunning / retry collection status. example: Unknown id: description: Invoice identifier. example: inv_01HXYZ type: string invoice_items: description: Line items on the invoice, including the resolved plan. items: $ref: '#/components/schemas/payments.MerchantPaymentInvoiceItem' type: array issuing_at: description: When the invoice was issued (RFC3339). example: '2024-06-15T14:32:10.000Z' type: string org_id: description: Organisation ID that owns this invoice. example: org_01HXYZ type: string payment_link: allOf: - $ref: '#/components/schemas/payments.MerchantPaymentPaylink' description: Payment link associated with this invoice, when one exists. payment_status: allOf: - $ref: '#/components/schemas/docenums.PaymentStatus' description: Status of the payment associated with this invoice. example: Succeeded reference: description: Merchant-defined invoice reference. example: order-10042 type: string source: allOf: - $ref: '#/components/schemas/docenums.BillingSource' description: Origin system or integration that created this invoice. example: BoomFi status: allOf: - $ref: '#/components/schemas/docenums.InvoiceStatus' description: Invoice status. example: Paid updated_at: description: When the invoice was last updated (RFC3339). example: '2024-06-15T14:33:01.000Z' type: string type: object payments.MerchantPaymentOrg: properties: id: description: Organisation display ID (org_...). example: org_01HXYZ type: string name: description: Organisation display name. example: Example Merchant type: string type: object payments.MerchantPaymentPaylink: properties: after_completion: allOf: - $ref: '#/components/schemas/paylinks.AfterCompletionStruct' description: >- Checkout behaviour after payment or when the link expires. Mirrors metadata.after_completion. created_at: description: When the payment link was created (RFC3339). example: '2024-05-01T12:00:00.000Z' type: string created_by: description: User or system that created the payment link. example: usr_01HXYZ type: string customer_ident_collection: description: Whether customer identity details are collected at checkout. example: false type: boolean deleted_at: description: When the payment link was soft-deleted (RFC3339), if applicable. type: string enabled: description: Whether this payment link is enabled. example: true type: boolean id: description: Payment link identifier. example: plink_01HXYZ type: string invoice_id: description: Invoice ID linked to this payment link. example: inv_01HXYZ type: string metadata: additionalProperties: {} description: Arbitrary merchant-defined metadata. type: object plan: allOf: - $ref: '#/components/schemas/models.PublicPlan' description: Plan copied from the top-level payment plan sub-document. plan_id: description: Plan ID linked to this payment link. example: pln_01HXYZ type: string properties: additionalProperties: {} description: Internal payment link properties. type: object shipping_address_collection: description: Whether a shipping address is collected at checkout. example: false type: boolean source: allOf: - $ref: '#/components/schemas/docenums.BillingSource' description: Origin system or integration that created this payment link. example: BoomFi tax_ident_collection: description: Whether a tax identifier is collected at checkout. example: false type: boolean updated_at: description: When the payment link was last updated (RFC3339). example: '2024-05-01T12:00:00.000Z' type: string updated_by: description: User or system that last updated the payment link. example: usr_01HXYZ type: string type: object docenums.PaymentMethod: enum: - Unknown - MerchantContract - ProxyWallet - Unblock - Payout - Card - GooglePay - ApplePay - Paypal - DirectDebit - Ramp - RampCryptoSettlement - Refund - Deposit type: string x-enum-varnames: - PaymentMethodUnknown - PaymentMethodMerchantContract - PaymentMethodProxyWallet - PaymentMethodUnblock - PaymentMethodPayout - PaymentMethodCard - PaymentMethodGooglePay - PaymentMethodApplePay - PaymentMethodPaypal - PaymentMethodDirectDebit - PaymentMethodRamp - PaymentMethodRampCryptoSettlement - PaymentMethodRefund - PaymentMethodDeposit models.PublicPayoutSplit: properties: address: description: >- On-chain wallet address or postal street address, depending on context. Empty for a bank payout, which has no address — see DestinationAccountID. type: string amount: description: Amount as a decimal string in major units. type: string chain_id: description: Blockchain chain ID. type: integer currency: description: Currency symbol (for example USDC or USD). type: string destination_account_id: description: >- Destination account id, when the payout was addressed to a registered account. type: integer reference: description: Merchant-defined reference string. type: string type: object payments.MerchantPaymentPlan: properties: created_at: description: When the resource was created (RFC3339). example: '2024-05-01T12:00:00.000Z' type: string currency: description: Currency symbol (for example USDC or USD). example: USDC type: string enabled: description: Whether this resource is enabled. example: true type: boolean expires_at: description: Expiration time (RFC3339). type: string id: description: Unique resource identifier. example: pln_01HXYZ type: string name: description: Display name. example: Starter type: string org_id: description: Organisation ID that owns this resource. example: org_01HXYZ type: string overrides: additionalProperties: $ref: '#/components/schemas/payments.MerchantPaymentPlanOverride' description: >- Fields that differ from the base plan after subscription or invoice overrides. type: object price: description: Price as a decimal string. example: '25.00' type: string recurring_interval: description: recurring only type: string recurring_interval_count: description: recurring only type: integer reference: description: Merchant-defined reference string. type: string trial_period: description: recurring only type: string type: description: Resource or value type. example: OneTime type: string updated_at: description: When the resource was last updated (RFC3339). example: '2024-05-01T12:00:00.000Z' type: string type: object payments.MerchantPaymentProperties: properties: action_state: allOf: - $ref: '#/components/schemas/payments.MerchantPaymentActionState' description: Current action state when the payment requires an external step. refund: allOf: - $ref: '#/components/schemas/payments.MerchantPaymentRefundRollup' description: >- How much of this payment has been refunded. Absent until a refund succeeds. type: object payments.MerchantPaymentRamp: properties: memo: description: Bank or off-ramp reference memo. example: INV-10042 type: string type: object payments.MerchantPaymentRefundedPlan: properties: id: description: Refunded plan identifier. type: string reference: description: Refunded plan merchant reference. type: string type: object docenums.BillingSource: enum: - Lago - BoomFi - Stripe - Chargebee - QuickBooks type: string x-enum-varnames: - BillingSourceLago - BillingSourceBoomFi - BillingSourceStripe - BillingSourceChargebee - BillingSourceQuickBooks docenums.PaymentStatus: enum: - Unknown - RequiresPaymentMethod - RequiresConfirmation - RequiresAction - Processing - Succeeded - Canceled - Failed type: string x-enum-varnames: - PaymentStatusUnknown - PaymentStatusRequiresPaymentMethod - PaymentStatusRequiresConfirmation - PaymentStatusRequiresAction - PaymentStatusProcessing - PaymentStatusSucceeded - PaymentStatusCanceled - PaymentStatusFailed internal.SingleError: properties: domain: description: |- Domain Example: orders example: orders type: string reason: description: |- Error Reason Example: InsufficientQuantity example: InsufficientQuantity type: string type: object docenums.TransactionStatus: enum: - Pending - Success - Failed type: string x-enum-varnames: - TransactionStatusPending - TransactionStatusSuccess - TransactionStatusFailed docenums.TransactionType: enum: - Unknown - Approval - Deposit - Withdraw - Payment - Refund - Subscribe - Unsubscribe - Internal - Swap - Redact - Retain - Verify - Authorize - Capture - Burn - Attestation - Mint type: string x-enum-varnames: - TransactionTypeUnknown - TransactionTypeApproval - TransactionTypeDeposit - TransactionTypeWithdraw - TransactionTypePayment - TransactionTypeRefund - TransactionTypeSubscribe - TransactionTypeUnsubscribe - TransactionTypeInternal - TransactionTypeSwap - TransactionTypeRedact - TransactionTypeRetain - TransactionTypeVerify - TransactionTypeAuthorize - TransactionTypeCapture - TransactionTypeBurn - TransactionTypeAttestation - TransactionTypeMint docenums.DunningStatus: enum: - Unknown - InProgress - Exhausted - Stopped - Succeeded type: string x-enum-varnames: - DunningStatusUnknown - DunningStatusInProgress - DunningStatusExhausted - DunningStatusStopped - DunningStatusSucceeded payments.MerchantPaymentInvoiceItem: properties: period_end_at: description: End of the billing period (RFC3339). type: string period_start_at: description: Start of the billing period (RFC3339). type: string plan: allOf: - $ref: '#/components/schemas/models.PublicPlan' description: Plan for a one-time invoice line. type: object docenums.InvoiceStatus: enum: - Unknown - Draft - Open - Paid - Void - Uncollectible type: string x-enum-varnames: - InvoiceStatusUnknown - InvoiceStatusDraft - InvoiceStatusOpen - InvoiceStatusPaid - InvoiceStatusVoid - InvoiceStatusUncollectible paylinks.AfterCompletionStruct: properties: custom_message: description: >- Custom message shown on the hosted success receipt after checkout completes. maxLength: 200 type: string failure_redirect_url: description: >- Failure URL. Hosted and lite checkout send the customer here when the payment link is expired or exhausted, or when payment.status is Failed. Optional for both hosted and redirect types. Not used when the payer switches payment method (Canceled). Max 512 characters. example: https://merchant.example/checkout/failed maxLength: 512 type: string redirect_url: description: >- Success URL. When type is redirect, hosted and lite checkout send the customer here after a successful payment (Succeeded). Required when type is redirect. Not used for expired links or Failed payments. Max 512 characters. example: https://merchant.example/checkout/success maxLength: 512 type: string type: description: >- After-completion behaviour: hosted keeps the customer on the in-app receipt; redirect sends them to redirect_url after a successful payment. When omitted, redirect_url implies redirect. enum: - hosted - redirect example: redirect type: string type: object models.PublicPlan: properties: created_at: description: When the resource was created (RFC3339). example: '2024-05-01T12:00:00.000Z' type: string currency: description: Currency symbol (for example USDC or USD). example: USDC type: string enabled: description: Whether this resource is enabled. example: true type: boolean expires_at: description: Expiration time (RFC3339). type: string id: description: Unique resource identifier. example: pln_01HXYZ type: string name: description: Display name. example: Starter type: string org_id: description: Organisation ID that owns this resource. example: org_01HXYZ type: string price: description: Price as a decimal string. example: '25.00' type: string recurring_interval: description: recurring only type: string recurring_interval_count: description: recurring only type: integer reference: description: Merchant-defined reference string. type: string trial_period: description: recurring only type: string type: description: Resource or value type. example: OneTime type: string updated_at: description: When the resource was last updated (RFC3339). example: '2024-05-01T12:00:00.000Z' type: string type: object payments.MerchantPaymentPlanOverride: properties: base: description: Value on the unmodified plan. value: description: Value after subscription or invoice overrides. type: object payments.MerchantPaymentActionState: properties: status: description: Current state of the action. example: Pending type: string type: description: Machine-readable action type. example: travel_rule type: string updated_at: description: When the action state was last updated (RFC3339). example: '2026-08-23T10:00:00.000Z' format: date-time type: string type: object payments.MerchantPaymentRefundRollup: properties: refunded: description: >- Whether the full amount has been returned. False for a partial refund. example: false type: boolean refunded_amount: description: Amount returned across all succeeded refunds, net of refund fees. example: '10.00' type: string type: object securitySchemes: ApiKeyAuth: in: header name: X-API-KEY type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.