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 |
{...}
|
---|
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 |
{...}
|
---|---|---|
400 | invalid_search_query_param |
{...}
|
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 |
{...}
|
---|---|---|
400 | api_unavailable |
{...}
|
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 |
{...}
|
---|---|---|
404 | not_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 |
{...}
|
---|---|---|
422 | invalid_resource |
{...}
|
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 |
{...}
|
---|---|---|
400 | dispute_already_under_review |
{...}
|
400 | dispute_already_resolved |
{...}
|
400 | dispute_already_cancelled |
{...}
|
400 | dispute_already_expired |
{...}
|
400 | dispute_already_won |
{...}
|
400 | dispute_already_lost |
{...}
|
400 | dispute_already_accepted |
{...}
|
400 | no_dispute_evidence_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 |
{...}
|
---|---|---|
400 | dispute_already_under_review |
{...}
|
400 | dispute_already_resolved |
{...}
|
400 | dispute_already_cancelled |
{...}
|
400 | dispute_already_expired |
{...}
|
400 | dispute_already_won |
{...}
|
400 | dispute_already_lost |
{...}
|
400 | dispute_already_accepted |
{...}
|
400 | no_dispute_evidence_provided |
{...}
|