API Reference

Disputes API

The disputes API allows you to retrieve details of disputes against your charges and perform actions to either challenge or accept them.

GET /disputes

Returns a paginated list of all disputes. With HEAD request, returns an empty response with an X-Total-Count header showing the total number of disputes.

Optional sort The field used to sort the disputes (received_at or evidence_required_by or amount).
Optional direction The direction in which to sort the disputes (1 for ascending or -1 for descending). Default value is 1.

Example

curl https://test-api.pinpayments.com/1/disputes -u your-secret-api-key:
200 OK 
{
  "response": [
    {
      "token": "dis_JRs6Xgk4jMyF33yGijQ7Nw",
      "category": "general",
      "status": "evidence_required",
      "amount": 100,
      "currency": "AUD",
      "charge": {
        "token": "ch_yJM0U_NaAsyY2A7Se3IFYQ",
        "success": true,
        "amount": 100,
        "currency": "AUD",
        "description": "test charge",
        "email": "roland@pinpayments.com",
        "ip_address": "203.192.1.172",
        "created_at": "2023-09-25T09:23:58Z",
        "status_message": "Success",
        "error_message": null,
        "card": {
          "token": "card_pIQJKMs93GsCc9vLSLevbw",
          "scheme": "master",
          "display_number": "XXXX-XXXX-XXXX-0000",
          "issuing_country": "AU",
          "expiry_month": 5,
          "expiry_year": 2025,
          "name": "Roland Robot",
          "address_line1": "42 Sevenoaks St",
          "address_line2": "",
          "address_city": "Lathlain",
          "address_postcode": "6454",
          "address_state": "WA",
          "address_country": "Australia",
          "network_type": null,
          "network_format": null,
          "customer_token": null,
          "primary": null
        },
        "transfer": [],
        "amount_refunded": 0,
        "total_fees": 33,
        "merchant_entitlement": 67,
        "refund_pending": false,
        "authorisation_token": null,
        "authorisation_expired": false,
        "authorisation_voided": false,
        "captured": true,
        "captured_at": "2023-09-25T09:23:58Z",
        "settlement_currency": "AUD",
        "active_chargebacks": false,
        "metadata": {
          "OrderNumber": "123456",
          "CustomerName": "Roland Robot"
        }
      },
      "evidence_required_by": "2023-10-15T00:00:00Z",
      "relevant_evidence": [
        "proof_of_delivery_or_service",
        "invoice_or_receipt",
        "invoice_showing_distinct_transactions",
        "customer_communication",
        "refund_or_cancellation_policy",
        "recurring_transaction_agreement",
        "additional_evidence"
      ],
      "received_at": "2023-09-25T09:23:58Z"
    }
  ],
  "count": 1,
  "pagination": {
    "current": 1,
    "previous": null,
    "next": null,
    "per_page": 25,
    "pages": 1,
    "count": 1
  }
}

Error Responses

401 unauthorized {...} 
{
  "error": "unauthorized",
  "error_description": "Not authorised"
}

GET /disputes/search

Returns a paginated list of disputes matching the search criteria. With HEAD request, returns an empty response with an X-Total-Count header showing the number of disputes matching the search criteria.

Optional query Return only disputes whose fields match the query. Fields covered include status and charge token (exact).
Optional status The status of the disputes
Optional sort The field used to sort the disputes (received_at or evidence_required_by or amount).
Optional direction The direction in which to sort the disputes (1 for ascending or -1 for descending). Default value is 1.

Example

curl https://test-api.pinpayments.com/1/disputes/search?query=evidence_required -u your-secret-api-key:
200 OK 
{
  "response": [
    {
      "token": "dis_JRs6Xgk4jMyF33yGijQ7Nw",
      "category": "general",
      "status": "evidence_required",
      "amount": 100,
      "currency": "AUD",
      "charge": {
        "token": "ch_yJM0U_NaAsyY2A7Se3IFYQ",
        "success": true,
        "amount": 100,
        "currency": "AUD",
        "description": "test charge",
        "email": "roland@pinpayments.com",
        "ip_address": "203.192.1.172",
        "created_at": "2023-09-25T09:23:58Z",
        "status_message": "Success",
        "error_message": null,
        "card": {
          "token": "card_pIQJKMs93GsCc9vLSLevbw",
          "scheme": "master",
          "display_number": "XXXX-XXXX-XXXX-0000",
          "issuing_country": "AU",
          "expiry_month": 5,
          "expiry_year": 2025,
          "name": "Roland Robot",
          "address_line1": "42 Sevenoaks St",
          "address_line2": "",
          "address_city": "Lathlain",
          "address_postcode": "6454",
          "address_state": "WA",
          "address_country": "Australia",
          "network_type": null,
          "network_format": null,
          "customer_token": null,
          "primary": null
        },
        "transfer": [],
        "amount_refunded": 0,
        "total_fees": 33,
        "merchant_entitlement": 67,
        "refund_pending": false,
        "authorisation_token": null,
        "authorisation_expired": false,
        "authorisation_voided": false,
        "captured": true,
        "captured_at": "2023-09-25T09:23:58Z",
        "settlement_currency": "AUD",
        "active_chargebacks": false,
        "metadata": {
          "OrderNumber": "123456",
          "CustomerName": "Roland Robot"
        }
      },
      "evidence_required_by": "2023-10-15T00:00:00Z",
      "relevant_evidence": [
        "proof_of_delivery_or_service",
        "invoice_or_receipt",
        "invoice_showing_distinct_transactions",
        "customer_communication",
        "refund_or_cancellation_policy",
        "recurring_transaction_agreement",
        "additional_evidence"
      ],
      "received_at": "2023-09-25T09:23:58Z"
    }
  ],
  "count": 1,
  "pagination": {
    "current": 1,
    "previous": null,
    "next": null,
    "per_page": 25,
    "pages": 1,
    "count": 1
  }
}

Error Responses

401 unauthorized {...} 
{
  "error": "unauthorized",
  "error_description": "Not authorised"
}
400 invalid_search_query_param {...} 
{
  "error": "invalid_search_query_param",
  "error_description": "The query parameter must be at least 3 characters in length"
}

GET /disputes/dispute-token

Returns the details of a dispute.

Example

curl https://test-api.pinpayments.com/1/disputes/dis_JRs6Xgk4jMyF33yGijQ7Nw -u your-secret-api-key:
200 OK 
{
  "response": {
    "token": "dis_JRs6Xgk4jMyF33yGijQ7Nw",
    "category": "general",
    "status": "evidence_required",
    "amount": 100,
    "currency": "AUD",
    "charge": {
      "token": "ch_yJM0U_NaAsyY2A7Se3IFYQ",
      "success": true,
      "amount": 100,
      "currency": "AUD",
      "description": "test charge",
      "email": "roland@pinpayments.com",
      "ip_address": "203.192.1.172",
      "created_at": "2023-09-25T09:23:58Z",
      "status_message": "Success",
      "error_message": null,
      "card": {
        "token": "card_pIQJKMs93GsCc9vLSLevbw",
        "scheme": "master",
        "display_number": "XXXX-XXXX-XXXX-0000",
        "issuing_country": "AU",
        "expiry_month": 5,
        "expiry_year": 2025,
        "name": "Roland Robot",
        "address_line1": "42 Sevenoaks St",
        "address_line2": "",
        "address_city": "Lathlain",
        "address_postcode": "6454",
        "address_state": "WA",
        "address_country": "Australia",
        "network_type": null,
        "network_format": null,
        "customer_token": null,
        "primary": null
      },
      "transfer": [],
      "amount_refunded": 0,
      "total_fees": 33,
      "merchant_entitlement": 67,
      "refund_pending": false,
      "authorisation_token": null,
      "authorisation_expired": false,
      "authorisation_voided": false,
      "captured": true,
      "captured_at": "2023-09-25T09:23:58Z",
      "settlement_currency": "AUD",
      "active_chargebacks": false,
      "metadata": {
        "OrderNumber": "123456",
        "CustomerName": "Roland Robot"
      }
    },
    "evidence_required_by": "2023-10-15T00:00:00Z",
    "relevant_evidence": [
      "proof_of_delivery_or_service",
      "invoice_or_receipt",
      "invoice_showing_distinct_transactions",
      "customer_communication",
      "refund_or_cancellation_policy",
      "recurring_transaction_agreement",
      "additional_evidence"
    ],
    "received_at": "2023-09-25T09:23:58Z"
  }
}

Error Responses

404 not_found {...} 
{
  "error": "not_found",
  "error_description": "The requested resource could not be found."
}
400 api_unavailable {...} 
{
  "error": "api_unavailable",
  "error_description": "This API is currently unavailable on your account. If you require access to this API please contact support@pinpayments.com"
}

GET /disputes/dispute-token/activity

Returns the activity feed for a dispute.

Example

curl https://test-api.pinpayments.com/1/disputes/dis_JRs6Xgk4jMyF33yGijQ7Nw/activity -u your-secret-api-key:
200 OK 
{
  "response": [
    {
      "type": "dispute.updated",
      "object": "dispute",
      "token": "dis_JRs6Xgk4jMyF33yGijQ7Nw",
      "status": "evidence_under_review",
      "created_at": "2023-09-11T08:10:18Z",
      "record": {
        "amount": 100,
        "currency": "AUD",
        "category": "general"
      }
    },
    {
      "type": "ledger_entry.created",
      "object": "ledger_entry",
      "status": "pending_transfer",
      "created_at": "2023-09-10T15:02:22Z",
      "record": {
        "annotation": "chargeback_recovery",
        "amount": -100,
        "currency": "AUD"
      }
    },
    {
      "type": "ledger_entry.created",
      "object": "ledger_entry",
      "status": "pending_transfer",
      "created_at": "2023-09-10T15:02:22Z",
      "record": {
        "annotation": "chargeback_fee",
        "amount": -2500,
        "currency": "AUD"
      }
    },
    {
      "type": "dispute.created",
      "object": "dispute",
      "token": "dis_JRs6Xgk4jMyF33yGijQ7Nw",
      "status": "evidence_required",
      "created_at": "2023-09-10T15:02:22Z",
      "record": {
        "amount": 100,
        "currency": "AUD",
        "category": "general"
      }
    },
    {
      "type": "charge.captured",
      "object": "charge",
      "token": "ch_yJM0U_NaAsyY2A7Se3IFYQ",
      "status": "succeeded",
      "created_at": "2023-09-01T09:23:58Z",
      "record": {
        "amount": 100,
        "currency": "AUD"
      }
    }
  ]
}

Error Responses

401 unauthorized {...} 
{
  "error": "unauthorized",
  "error_description": "Not authorised"
}
404 not_found {...} 
{
  "error": "not_found",
  "error_description": "The requested resource could not be found."
}

GET /disputes/dispute-token/evidence

Displays current evidence batch for a dispute.

Example

curl https://test-api.pinpayments.com/1/disputes/dis_JRs6Xgk4jMyF33yGijQ7Nw/evidence -u your-secret-api-key:
200 OK 
{
  "response": {
    "additional_evidence_file": {
      "token": "file_gYa1wYuzLgSkG-tJ4gV8MA",
      "original_filename": "cat.jpeg",
      "presigned_url": "https://pin-gateway-api-files-production-sandbox.s3.ap-southeast-2.amazonaws.com/sample.jpg",
      "presigned_url_expires_at": "2023-09-19T05:08:16Z",
      "purpose": "dispute_evidence",
      "size": 8060,
      "mime_type": "image/jpeg",
      "uploaded_at": "2023-09-19T04:08:16Z"
    }
  }
}

PUT /disputes/dispute-token/evidence

Updates evidence batch for a dispute.

Optional additional_evidence_file File of additional evidence related to the disputes.
Optional additional_evidence_text Text of additional evidence related to the disputes.
Optional customer_communication_file Discussion with the customer related to the disputes in file format.
Optional customer_communication_text Discussion with the customer related to the disputes in text format.
Optional invoice_or_receipt_file Invoice related to the disputes in file format.
Optional invoice_or_receipt_text Invoice related to the disputes in text format.
Optional invoice_showing_distinct_transactions_file Invoice showing transactions related to the disputes in file format.
Optional invoice_showing_distinct_transactions_text Invoice showing transactions related to the disputes in text format.
Optional proof_of_delivery_or_service_file Evidence showing proof of delivery of good or service related to the disputes in file format.
Optional proof_of_delivery_or_service_text Evidence showing proof of delivery of good or service related to the disputes in text format.
Optional recurring_transaction_agreement_file Agreement showing recurring transaction contract with customer in file format
Optional recurring_transaction_agreement_text Agreement showing recurring transaction contract with customer in text format
Optional refund_or_cancellation_policy_file Copy of refund or cancellation policy related to disputes in file format
Optional refund_or_cancellation_policy_text Copy of refund or cancellation policy related to disputes in text format

Example

curl https://test-api.pinpayments.com/1/disputes/dis_JRs6Xgk4jMyF33yGijQ7Nw/evidence -u your-secret-api-key: -X PUT \
 -d "additional_evidence_file=file_flU4sKYI_R7kJ2mNcvJSYg"
200 OK 
{
  "response": {
    "additional_evidence_file": {
      "token": "file_gYa1wYuzLgSkG-tJ4gV8MA",
      "original_filename": "cat.jpeg",
      "presigned_url": "https://pin-gateway-api-files-production-sandbox.s3.ap-southeast-2.amazonaws.com/sample.jpg",
      "presigned_url_expires_at": "2023-09-19T05:08:16Z",
      "purpose": "dispute_evidence",
      "size": 8060,
      "mime_type": "image/jpeg",
      "uploaded_at": "2023-09-19T04:08:16Z"
    }
  }
}

Error Responses

401 unauthorized {...} 
{
  "error": "unauthorized",
  "error_description": "Not authorised"
}
422 invalid_resource {...} 
{
  "error": "invalid_resource",
  "error_description": "One or more parameters were missing or invalid",
  "messages": [
    {
      "code": "additional_evidence_text_invalid",
      "message": "Additional evidence text is too long (maximum is 500 characters)",
      "param": "additional_evidence_text"
    },
    {
      "code": "additional_evidence_file_invalid",
      "message": "Additional evidence file does not exist",
      "param": "additional_evidence_file"
    }
  ]
}

POST /disputes/dispute-token/evidence

Submits current evidence batch for review.

Example

curl https://test-api.pinpayments.com/1/disputes/dis_JRs6Xgk4jMyF33yGijQ7Nw/evidence -u your-secret-api-key:
200 OK
No response body.

Error Responses

401 unauthorized {...} 
{
  "error": "unauthorized",
  "error_description": "Not authorised"
}
400 dispute_already_under_review {...} 
{
  "error": "dispute_already_under_review",
  "error_description": "The dispute is already under review"
}
400 dispute_already_resolved {...} 
{
  "error": "dispute_already_resolved",
  "error_description": "The dispute has already been resolved"
}
400 dispute_already_cancelled {...} 
{
  "error": "dispute_already_cancelled",
  "error_description": "The dispute has already been cancelled"
}
400 dispute_already_expired {...} 
{
  "error": "dispute_already_expired",
  "error_description": "The dispute has already expired"
}
400 dispute_already_won {...} 
{
  "error": "dispute_already_won",
  "error_description": "The dispute was already won"
}
400 dispute_already_lost {...} 
{
  "error": "dispute_already_lost",
  "error_description": "The dispute was already lost"
}
400 dispute_already_accepted {...} 
{
  "error": "dispute_already_accepted",
  "error_description": "The dispute has already been accepted"
}
400 no_dispute_evidence_provided {...} 
{
  "error": "no_dispute_evidence_provided",
  "error_description": "No dispute evidence has been provided"
}

POST /disputes/dispute-token/accept

Accepts a dispute.

Example

curl https://test-api.pinpayments.com/1/disputes/dis_JRs6Xgk4jMyF33yGijQ7Nw/accept -u your-secret-api-key: -X POST
200 OK
No response body.

Error Responses

401 unauthorized {...} 
{
  "error": "unauthorized",
  "error_description": "Not authorised"
}
400 dispute_already_under_review {...} 
{
  "error": "dispute_already_under_review",
  "error_description": "The dispute is already under review"
}
400 dispute_already_resolved {...} 
{
  "error": "dispute_already_resolved",
  "error_description": "The dispute has already been resolved"
}
400 dispute_already_cancelled {...} 
{
  "error": "dispute_already_cancelled",
  "error_description": "The dispute has already been cancelled"
}
400 dispute_already_expired {...} 
{
  "error": "dispute_already_expired",
  "error_description": "The dispute has already expired"
}
400 dispute_already_won {...} 
{
  "error": "dispute_already_won",
  "error_description": "The dispute was already won"
}
400 dispute_already_lost {...} 
{
  "error": "dispute_already_lost",
  "error_description": "The dispute was already lost"
}
400 dispute_already_accepted {...} 
{
  "error": "dispute_already_accepted",
  "error_description": "The dispute has already been accepted"
}
400 no_dispute_evidence_provided {...} 
{
  "error": "no_dispute_evidence_provided",
  "error_description": "No dispute evidence has been provided"
}
Pin Payments acknowledges the Traditional Owners and Custodians of the Country throughout Australia and recognises their continuing connection to land, water and community.
We pay our respects to Aboriginal and Torres Strait Islander cultures, and to Elders past and present.