Skip to main content

​
Overview

If a transaction on your Yativo Card was unauthorized, incorrect, or you did not receive goods or services paid for, you can file a dispute through the API. Disputes require a valid reason code and a description of the issue.
Disputes should be filed as soon as possible after identifying a problem. Most card networks require disputes to be submitted within 60–120 days of the transaction date.
interface DisputeReason {
  code: string;
  description: string;
  category: string;
}

interface CreateDisputeRequest {
  reason_code: string;
  description?: string;
}

interface Dispute {
  dispute_id: string;
  transaction_id: string;
  reason_code: string;
  status: "submitted" | "under_review" | "resolved" | "rejected";
  created_at: string;
}

​
Get Dispute Reason Codes

Before submitting a dispute, retrieve the list of valid reason codes for your account type. 
GET /yativo-card/{yativoCardId}/transactions/dispute-reasons
​
yativoCardId
string
required
Your Yativo Card account ID.
curl -X GET 'https://crypto-api.yativo.com/api/yativo-card/yc_01HX9KZMB3F7VNQP8R2WDGT4E5/transactions/dispute-reasons' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "status": "success",
  "data": [
    {
      "reason_code": "UNAUTHORIZED",
      "description": "Transaction was not authorized by the cardholder"
    },
    {
      "reason_code": "DUPLICATE",
      "description": "Transaction was charged more than once for the same purchase"
    },
    {
      "reason_code": "NOT_RECEIVED",
      "description": "Goods or services were not received"
    },
    {
      "reason_code": "NOT_AS_DESCRIBED",
      "description": "Goods or services were significantly different from what was described"
    },
    {
      "reason_code": "CANCELLED",
      "description": "Subscription or service was cancelled but charge still occurred"
    },
    {
      "reason_code": "INCORRECT_AMOUNT",
      "description": "Transaction amount was incorrect"
    },
    {
      "reason_code": "CREDIT_NOT_PROCESSED",
      "description": "A refund or credit was agreed upon but not posted"
    }
  ]
}

​
File a Dispute

Submit a dispute for a specific transaction. 
POST /yativo-card/{yativoCardId}/transactions/{transactionId}/dispute
​
yativoCardId
string
required
Your Yativo Card account ID.
​
transactionId
string
required
The transaction ID to dispute. Retrieve this from the transactions endpoint.
​
reason_code
string
required
A valid dispute reason code from the reasons list (e.g., "UNAUTHORIZED", "NOT_RECEIVED").
​
description
string
required
A detailed description of the dispute. Minimum 20 characters. Include relevant details such as merchant name, transaction date, and what happened.
curl -X POST 'https://crypto-api.yativo.com/api/yativo-card/yc_01HX9KZMB3F7VNQP8R2WDGT4E5/transactions/txn_01HX9KZMB3F7VNQP8R2WDGT901/dispute' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "reason_code": "UNAUTHORIZED",
    "description": "I did not authorize this transaction at Amazon on March 20, 2026 for $42.50. My card was in my possession at the time and I did not make this purchase."
  }'

{
  "status": "success",
  "data": {
    "dispute_id": "dsp_01HX9KZMB3F7VNQP8R2WDGT999",
    "transaction_id": "txn_01HX9KZMB3F7VNQP8R2WDGT901",
    "reason_code": "UNAUTHORIZED",
    "status": "submitted",
    "submitted_at": "2026-03-25T16:00:00Z",
    "expected_resolution_by": "2026-04-24T16:00:00Z"
  }
}

​
Common Dispute Reason Codes

Use this reason code when you see a transaction on your card that you did not make and did not authorize anyone else to make. This typically indicates fraudulent use or card compromise.What to include in your description:
  • Where you were at the time of the transaction
  • Whether your card was in your possession
  • Whether you have shared your card details with anyone
Use when a merchant has charged you more than once for the same purchase.What to include:
  • The dates of both charges
  • Order or receipt numbers if available
  • Any communication with the merchant about the duplicate
Use when you paid for goods or services but never received them, and the merchant has not issued a refund.What to include:
  • Expected delivery or service date
  • Evidence of merchant contact (email threads, support tickets)
  • Whether tracking shows non-delivery (for physical goods)
Use when a subscription, service, or order was cancelled but you were still charged after the cancellation date.What to include:
  • Cancellation date and confirmation number
  • The charge date relative to the cancellation
  • Any confirmation emails from the merchant
Use when the amount charged differs from the agreed price or invoice.What to include:
  • The amount you expected to be charged
  • The amount actually charged
  • Receipts or invoices showing the agreed price

​
B2B Issuer: Dispute Endpoints

If you are operating as a Card Issuer and managing disputes on behalf of your customers, use the B2B dispute endpoints:

​
Get Dispute Reasons (B2B)

GET /yativo-card/customers/{yativoCardId}/transactions/dispute-reasons

curl -X GET 'https://crypto-api.yativo.com/api/yativo-card/customers/yc_customer_01HX9KZMB3F7/transactions/dispute-reasons' \
  -H 'Authorization: Bearer YOUR_ISSUER_API_KEY'

​
File a Dispute (B2B)

POST /yativo-card/customers/{yativoCardId}/transactions/{transactionId}/dispute

curl -X POST 'https://crypto-api.yativo.com/api/yativo-card/customers/yc_customer_01HX9KZMB3F7/transactions/txn_01HX9KZMB3F7VNQP8R2WDGT901/dispute' \
  -H 'Authorization: Bearer YOUR_ISSUER_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "reason_code": "NOT_RECEIVED",
    "description": "Customer reports they did not receive the goods ordered on March 18, 2026. Multiple attempts to contact the merchant have been unsuccessful."
  }'

{
  "status": "success",
  "data": {
    "dispute_id": "dsp_01HX9KZMB3F7VNQP8R2WDGT888",
    "transaction_id": "txn_01HX9KZMB3F7VNQP8R2WDGT901",
    "customer_id": "yc_customer_01HX9KZMB3F7",
    "reason_code": "NOT_RECEIVED",
    "status": "submitted",
    "submitted_at": "2026-03-25T16:30:00Z",
    "expected_resolution_by": "2026-04-24T16:30:00Z"
  }
}

​
Dispute Process Timeline

PhaseTypical DurationDescription
SubmissionImmediateDispute is submitted and acknowledged.
Review3–5 business daysInternal review of the dispute details.
Chargeback Filing5–10 business daysDispute is escalated to the card network if valid.
Merchant ResponseUp to 30 daysMerchant is given time to respond or accept the chargeback.
Resolution30–90 days totalFinal decision is made and any credits are applied.
Providing clear, detailed descriptions and any supporting documentation significantly improves the likelihood of a successful dispute outcome and speeds up the resolution process.
Filing a fraudulent dispute is a violation of the cardholder agreement and may result in account suspension. Only submit disputes for genuine issues.