Biftpaydocs
Dashboard

Disputes

List disputes

get/v1/disputes

Parameters

statusneeds_response | under_review | won | lostin query
bash
curl https://sandbox.api.biftpay.com/v1/disputes \
  -H "Authorization: Bearer bp_test_..."

Responses

  • 200
    OKobject
    Fields
    object"list"required
    dataarray of Disputerequired
    Fields of data
    idstring (uuid)required
    object"dispute"required
    livemodebooleanrequired
    merchant_idstring (uuid)required
    payment_intentstring (uuid)required
    amountintegerrequired

    Minor units (kobo, cents).

    at least 0

    held_amountintegerrequired

    Minor units (kobo, cents).

    at least 0

    currencyNGN | USDrequired
    reasonfraudulent | product_not_received | duplicate | credit_not_processed | generalrequired
    statusneeds_response | under_review | won | lostrequired
    respond_bystring (date-time)required
    evidencestring | null
    evidence_submitted_atstring (date-time) | null
    created_atstring (date-time)required
    resolved_atstring (date-time) | null
    feeintegerrequired

    Chargeback fee, charged when the dispute is lost (0 otherwise).

    at least 0

    fee_vatintegerrequired

    VAT on the chargeback fee.

    at least 0

    has_moreboolean

Retrieve a dispute

get/v1/disputes/{id}

Parameters

idstring (uuid)in pathrequired
bash
curl https://sandbox.api.biftpay.com/v1/disputes/{id} \
  -H "Authorization: Bearer bp_test_..."

Responses

  • 200
    OKDispute
    Fields
    idstring (uuid)required
    object"dispute"required
    livemodebooleanrequired
    merchant_idstring (uuid)required
    payment_intentstring (uuid)required
    amountintegerrequired

    Minor units (kobo, cents).

    at least 0

    held_amountintegerrequired

    Minor units (kobo, cents).

    at least 0

    currencyNGN | USDrequired
    reasonfraudulent | product_not_received | duplicate | credit_not_processed | generalrequired
    statusneeds_response | under_review | won | lostrequired
    respond_bystring (date-time)required
    evidencestring | null
    evidence_submitted_atstring (date-time) | null
    created_atstring (date-time)required
    resolved_atstring (date-time) | null
    feeintegerrequired

    Chargeback fee, charged when the dispute is lost (0 otherwise).

    at least 0

    fee_vatintegerrequired

    VAT on the chargeback fee.

    at least 0

  • 404
    Not found, or not visible to this key

The dispute's evidence files

get/v1/disputes/{id}/files

Parameters

idstring (uuid)in pathrequired
bash
curl https://sandbox.api.biftpay.com/v1/disputes/{id}/files \
  -H "Authorization: Bearer bp_test_..."

Responses

  • 200
    OKFileList
    Fields
    object"list"required
    dataarray of Filerequired
    Fields of data
    idstring (uuid)required
    object"file"required
    file_namestringrequired
    content_typestringrequired
    sizeintegerrequired
    uploaded_bymerchant | biftpayrequired
    messagestring (uuid) | nullrequired

    The case message it's attached to.

    created_atstring (date-time)required
    has_morebooleanrequired
  • 404
    Not found, or not visible to this key

Attach evidence (receipt, delivery proof, messages) before responding

post/v1/disputes/{id}/files

Up to 10 files, while the dispute needs a response and before the deadline (409 dispute_not_open, response_deadline_passed).

Parameters

idstring (uuid)in pathrequired
Idempotency-Keystringin headerrequired

A unique key per logical request, for example a UUID. Up to 255 characters.

up to 255 characters

Body

file_namestringrequired

up to 200 characters

content_typeapplication/pdf | image/jpeg | image/pngrequired
datastringrequired

Base64; up to 5 MB decoded

bash
curl -X POST https://sandbox.api.biftpay.com/v1/disputes/{id}/files \
  -H "Authorization: Bearer bp_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "…",
    "content_type": "application/pdf",
    "data": "…"
  }'

Responses

  • 201
    The fileFile
    Fields
    idstring (uuid)required
    object"file"required
    file_namestringrequired
    content_typestringrequired
    sizeintegerrequired
    uploaded_bymerchant | biftpayrequired
    messagestring (uuid) | nullrequired

    The case message it's attached to.

    created_atstring (date-time)required
  • 400
    Invalid request
  • 404
    Not found, or not visible to this key
  • 409
    The object is in a state that doesn't allow this

One evidence file's content

get/v1/disputes/{id}/files/{fileId}

Parameters

idstring (uuid)in pathrequired
fileIdstring (uuid)in pathrequired
bash
curl https://sandbox.api.biftpay.com/v1/disputes/{id}/files/{fileId} \
  -H "Authorization: Bearer bp_test_..."

Responses

  • 200
    The file, base64FileContent
    Fields
    object"file_content"required
    file_namestringrequired
    content_typestringrequired
    datastringrequired

    Base64

  • 404
    Not found, or not visible to this key

Remove an evidence file (before responding)

post/v1/disputes/{id}/files/{fileId}/remove

Parameters

idstring (uuid)in pathrequired
fileIdstring (uuid)in pathrequired
Idempotency-Keystringin headerrequired

A unique key per logical request, for example a UUID. Up to 255 characters.

up to 255 characters

bash
curl -X POST https://sandbox.api.biftpay.com/v1/disputes/{id}/files/{fileId}/remove \
  -H "Authorization: Bearer bp_test_..." \
  -H "Idempotency-Key: $(uuidgen)"

Responses

  • 200
    The remaining filesFileList
    Fields
    object"list"required
    dataarray of Filerequired
    Fields of data
    idstring (uuid)required
    object"file"required
    file_namestringrequired
    content_typestringrequired
    sizeintegerrequired
    uploaded_bymerchant | biftpayrequired
    messagestring (uuid) | nullrequired

    The case message it's attached to.

    created_atstring (date-time)required
    has_morebooleanrequired
  • 404
    Not found, or not visible to this key
  • 409
    The object is in a state that doesn't allow this

Submit evidence (once, before respond_by)

post/v1/disputes/{id}/respond

Parameters

idstring (uuid)in pathrequired
Idempotency-Keystringin headerrequired

A unique key per logical request, for example a UUID. Up to 255 characters.

up to 255 characters

Body

evidencestringrequired

up to 10000 characters

bash
curl -X POST https://sandbox.api.biftpay.com/v1/disputes/{id}/respond \
  -H "Authorization: Bearer bp_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "evidence": "…"
  }'

Responses

  • 200
    OKDispute
    Fields
    idstring (uuid)required
    object"dispute"required
    livemodebooleanrequired
    merchant_idstring (uuid)required
    payment_intentstring (uuid)required
    amountintegerrequired

    Minor units (kobo, cents).

    at least 0

    held_amountintegerrequired

    Minor units (kobo, cents).

    at least 0

    currencyNGN | USDrequired
    reasonfraudulent | product_not_received | duplicate | credit_not_processed | generalrequired
    statusneeds_response | under_review | won | lostrequired
    respond_bystring (date-time)required
    evidencestring | null
    evidence_submitted_atstring (date-time) | null
    created_atstring (date-time)required
    resolved_atstring (date-time) | null
    feeintegerrequired

    Chargeback fee, charged when the dispute is lost (0 otherwise).

    at least 0

    fee_vatintegerrequired

    VAT on the chargeback fee.

    at least 0

  • 404
    Not found, or not visible to this key
  • 409
    The object is in a state that doesn't allow this