Skip to main content

Payments

ONVO payment flows are built around payment intents, payment methods, refunds, and asynchronous events.

Main resources​

ResourceDescription
Payment intentRepresents the attempt to charge an order.
Payment methodInstrument used by the buyer.
SubscriptionCharges a customer periodically using a recurring price.
RefundFull or partial return of a payment.
WebhookEvent sent by ONVO when state changes.

For most integrations, create one intent per order and listen to webhooks to confirm the final result.

Card verification declines​

When you create or update a card payment method, ONVO tokenizes and verifies the card before storing its details. If verification fails, the response preserves the general cards.invalid_card_info error and can include details.card with structured information for the merchant.

details.card is optional. When present, it contains these fields:

  • reason: stable category for choosing the general treatment.
  • declineCode: safe code from the gateway or issuer, or an ONVO fallback value.
  • declineMessage: safe informational text for logging or support.

For example, a decline can return this response:

{
  "statusCode": 400,
  "type": "OnvoAPIError",
  "code": "cards.invalid_card_info",
  "message": "There was an error with the card information provided. Please review card number, expiration date and cvv",
  "path": "/v1/payment-methods",
  "details": {
    "card": {
      "reason": "issuer_declined",
      "declineCode": "55",
      "declineMessage": "Incorrect PIN"
    }
  },
  "timestamp": "2026-04-29T17:36:28.477Z"
}

How to interpret reason​

ValueWhen it is used
issuer_declinedThe issuer declined verification, for example because of incorrect details or a card restriction.
gateway_declinedThe gateway or acquirer explicitly reported a non-technical acceptance, authentication, merchant, or risk rule.
onvo_declinedONVO applied an eligibility or security rule, such as a disallowed brand or BIN.
processor_errorA technical, communication, or configuration problem prevented verification from completing.
unknownThere was not enough information to attribute the decline safely.

Use reason for general logic. declineCode is not part of a universal code namespace and can vary by provider; do not build global rules that assume the same code always has the same meaning. declineMessage is also informational: do not parse it for decisions or depend on it for localization.

When no specific decline information is available, ONVO returns the default values: unknown in reason, generic_decline in declineCode, and a generic message in declineMessage.

  1. Check the top-level code first to identify cards.invalid_card_info.
  2. If details.card exists, use reason to choose the general buyer experience.
  3. Show your own safe guidance to the buyer; do not expose internal messages or promise that retrying will resolve the decline.
  4. Record declineCode and declineMessage only as context for diagnostics and support.

Reference and examples​