WePay logo
      Nothing Found

Create a refund

post/refunds

The POST /refunds call allows your platform to create a new refund. Refunds facilitate the return of money from the merchant to the payer. Note: A Payment must be created within the last 60 days and have a status of complete in order to refund it. If your platform has a custom refund limit, then use that number instead.

SecurityappIdAuth and appTokenAuth
Request
header Parameters
Api-Version
required
string
Example: 3.0
Content-Type
required
stringapplication/json
Example: application/json
Unique-Key
required
string
Request Body schema: application/json
payment_id
required
string [ 1 .. 255 ] characters

ID of the object or resource.

refund_reason
required
string [ 1 .. 65535 ] characters
object or null

The amount of the refund when not performing a full refund.

object or null

Any custom data your platform chooses to attach to this resource. The custom data must be key-value pairs and not contain any personally identifiable information (PII) or payment card (PCI) data.

is_unreferenced_refund
boolean

Note: This parameter is currently only available in the closed BETA for Unreferenced Refunds. If you are not working with your integration team at WePay to implement Unreferenced Refunds, please be sure to exclude this parameter from your requests altogether; even sending a value of null will result in an error for apps not participating in the closed BETA.

order_id
string [ 1 .. 255 ] characters

ID of the object or resource.

Array of objects or null

Any rbit data your platform chooses to attach to this resource. The rbit data must be key-value pairs and can be an array of rbit objects.

reference_id
string or null [ 1 .. 255 ] characters

A custom reference ID for your platform to track the object. It can be any string.

Responses
201
Response Schema: application/json
required
object or null

The amount of the refund when not performing a full refund.

id
required
string

ID of the refund, generated by WePay when the refund is created.

resource
required
string

Helps organize information by identifying the resource type of the object data.

Value: Description
refunds
path
required
string

Path of resource and resource ID.

create_time
required
integer <int64> >= 0

The time (in UNIX) when the refund was created.

required
object or null

Details the owner resource and owner path.

status
required
string

Status of the refund. Possible values include: pending, completed, failed.

required
object or null

The resource ID and path for the Order that your app created and associated with the payment.

required
object or null

The payment linked to this refund or dispute.

required
object
refund_reason
required
string

The reason for this refund.

required
Array of objects or null or null

Explains why refund is pending and may contain an array of reasons.

required
object or null
required
object or null

If a refund has occurred, fetch this transaction record to account for the portion of the refund debited from the merchant.

required
object or null

If a refund has occurred, fetch this transaction record to account for the portion of the refund debited from your platform account balance.

is_unreferenced_refund
required
boolean

Note: This parameter is currently only available in the closed BETA for Unreferenced Refunds. If you are not working with your integration team at WePay to implement Unreferenced Refunds, please be sure to exclude this parameter from your requests altogether; even sending a value of null will result in an error for apps not participating in the closed BETA.

required
object or null

Any custom data your platform chooses to attach to this resource. The custom data must be key-value pairs and not contain any personally identifiable information (PII) or payment card (PCI) data.

api_version
string
reference_id
string or null [ 1 .. 255 ] characters

A custom reference ID for your platform to track the object. It can be any string.

400

INVALID_PARAMS, PAYMENT_CANNOT_BE_REFUNDED

403

NOT_AUTHORIZED

500

UNEXPECTED_ERROR

Request samples
application/json
{
  • "amounts": {
    • "total_amount": 300,
    • "currency": "USD",
    • "fee_refund_amount": 50
    },
  • "order_id": "ordr-123-abc",
  • "payment_id": "18752aba-25d0-4328-aac9-a0ba7216eb67",
  • "refund_reason": "Item(s) returned",
  • "reference_id": "reference_id_0"
}
Response samples
application/json
{
  • "amounts": {
    • "total_amount": 100,
    • "currency": "USD",
    • "fee_refund_amount": 0
    },
  • "create_time": 1509140695,
  • "custom_data": null,
  • "failure_reason": null,
  • "id": "9b53d5fd-17b1-400c-b197-3204f4d6171c",
  • "order": null,
  • "owner": {
    • "id": "40200612-e849-4172-8308-657cf3a0de27",
    • "path": "/accounts/40200612-e849-4172-8308-657cf3a0de2",
    • "resource": "accounts"
    },
  • "path": "/refunds/9b53d5fd-17b1-400c-b197-3204f4d6171c",
  • "payment": {
    • "id": "a8ca756e-5a62-4c2a-80fd-9b82563d47cb",
    • "path": "/payments/a8ca756e-5a62-4c2a-80fd-9b82563d47cb",
    • "resource": "payments"
    },
  • "payment_method": {
    • "id": "00000000-6363-0000-0000-0000c27db2f3",
    • "path": "/payment_methods/00000000-6363-0000-0000-0000c27db2f3",
    • "resource": "payment_methods"
    },
  • "pending_reasons": null,
  • "refund_reason": "example refund reason",
  • "resource": "refunds",
  • "status": "completed",
  • "txnr_app_fee_refund": null,
  • "txnr_merchant_refund": {
    • "id": "7c59ebf4-d6ae-4125-85f8-515b95725501",
    • "path": "/transaction_records/7c59ebf4-d6ae-4125-85f8-515b95725501",
    • "resource": "transaction_records"
    },
  • "is_unreferenced_refund": false,
  • "api_version": "3.2",
  • "reference_id": "reference_id_0"
}