Refund
POST
/refundsCreate Refund
Body — CreateRefundDTO: exactly one of charge_id, charge or payment_intent (resolves to its captured charge); amount optional (> 0, defaults to what is left to refund); reason optional: duplicate, fraudulent or requested_by_customer. Stripe flow: there is no approval step. The refund is sent to the provider at once and the response is the refund with status pending, requires_action, succeeded or failed (a failed refund still returns 200, with failure_reason). A refund always goes back to the original payment method: destination may only be source, and customer_balance_id / forex_quote_id are refused (E4515). A payment method with no refund API is refused with E4526. Reusing an Idempotency-Key for a different charge or amount returns E4529.
Request
Example
curl -X POST 'https://api.paycose.com/api/v1/app1/platform/wallet/refunds/' \
-H 'X-Session-Token: {{session_token}}' \
-H 'X-Country: {{country}}' \
-d '{
"amount": null,
"reason": "requested_by_customer",
"destination": null,
"charge_id": null,
"charge": "{{charge_id}}",
"payment_intent": null,
"metadata": {},
"customer_balance_id": null,
"forex_quote_id": null,
"refund_application_fee": false,
"reverse_transfer": false,
"labels": []
}'Headers
| Name | Value |
|---|---|
| X-Session-Token | {{session_token}} |
| X-Country | {{country}} |
Body
| Name | Type | Value |
|---|---|---|
| amount | null | null |
| reason | string | requested_by_customer |
| destination | null | null |
| charge_id | null | null |
| charge | string | {{charge_id}} |
| payment_intent | null | null |
| metadata | object | {…} |
| customer_balance_id | null | null |
| forex_quote_id | null | null |
| refund_application_fee | boolean | false |
| reverse_transfer | boolean | false |
| labels | array | [0] |
{
"amount": null,
"reason": "requested_by_customer",
"destination": null,
"charge_id": null,
"charge": "{{charge_id}}",
"payment_intent": null,
"metadata": {},
"customer_balance_id": null,
"forex_quote_id": null,
"refund_application_fee": false,
"reverse_transfer": false,
"labels": []
}Responses
200200 OK
Headers
| Name | Value |
|---|---|
| Content-Type | application/json |
Body
{
"id": "<string>",
"object": "<string>",
"livemode": false,
"created_at": null,
"updated_at": null,
"number": "<string>",
"charge_id": "<string>",
"payment_intent": "<string>",
"amount_from_merchant": 0,
"amount_from_app": 0,
"amount": 0,
"currency": "<string>",
"scaling_factor": 0,
"status": "<string>",
"reason": "<string>",
"rejection_reason": "<string>",
"failure_reason": "<string>",
"balance_transaction": "<string>",
"failure_balance_transaction": "<string>",
"destination": "<RefundDestination>",
"idempotency_key": "<string>",
"requested_at": "<RFC3339 timestamp>",
"processed_at": "<RFC3339 timestamp>",
"provider": "<string>",
"reference_id": "<string>",
"metadata": {},
"labels": "<core.Labels>",
"charge": {
"id": "<string>",
"object": "<string>",
"livemode": false,
"created_at": "<RFC3339 timestamp>",
"updated_at": "<RFC3339 timestamp>",
"status": "<string>",
"customer_id": "<string>",
"payment_method_id": "<string>",
"payment_intent": "<string>",
"amount": 0,
"application_fee_amount": 0,
"application_tax_amount": 0,
"net_amount": 0,
"application": "<string>",
"application_fee": "<string>",
"transfer": "<string>",
"on_behalf_of": "<string>",
"transfer_group": "<string>",
"amount_refunded": 0,
"amount_captured": 0,
"amount_capturable": 0,
"amount_voided": 0,
"currency": "<string>",
"scaling_factor": 0,
"paid": false,
"canceled": false,
"refunded": false,
"captured": false,
"capture_method": "<string>",
"settlement_status": "<string>",
"failure_reason": "<string>",
"failure_code": "<string>",
"failure_message": "<string>",
"reason_source": "<string>",
"expires_at": "<RFC3339 timestamp>",
"canceled_at": "<RFC3339 timestamp>",
"disputed": false,
"dispute_id": "<string>",
"dispute_status": "<string>",
"dispute_reason": "<string>",
"dispute_amount": 0,
"transfer_data": {
"destination": "<string>",
"amount": 0,
"balance_id": "<string>"
},
"provider": "<string>",
"plane": "<string>",
"gateway_fee_amount": 0,
"credit_covered_fee_amount": 0,
"provider_fee_amount": 0,
"payable_amount": 0,
"reference_id": "<string>",
"metadata": {},
"labels": "<core.Labels>",
"next_action": [
{
"type": "<string>",
"title": "<string>",
"description": "<string>",
"i18n_key": "<string>",
"url": "<string>",
"client_secret": "<string>",
"payment_method": "<string>",
"qr_data": "<string>"
}
],
"promptpay": {
"raw": "<string>",
"image": "<string>",
"ref1": "<string>",
"ref2": "<string>",
"ref3": "<string>",
"expires_at": "<RFC3339 timestamp>"
},
"installment": {
"term": 0,
"issuer": "<string>",
"card_face_id": "<string>",
"interest_amount": 0,
"absorption": "<string>",
"monthly_amount": 0,
"first_amount": 0
},
"customer": {
"id": "<string>",
"object": "<string>",
"livemode": false,
"created_at": null,
"updated_at": null,
"name": "<string>",
"email": "<string>",
"phone": "<string>",
"address": {
"city": "<string>",
"country": "<string>",
"line1": "<string>",
"line2": "<string>",
"postal_code": "<string>",
"state": "<string>"
},
"shipping": {
"name": "<string>",
"phone": "<string>",
"address": {
"city": "<string>",
"country": "<string>",
"line1": "<string>",
"line2": "<string>",
"postal_code": "<string>",
"state": "<string>"
}
},
"is_system": false,
"is_application_customer": false,
"capabilities": {
"charge": false,
"transfer": false,
"payout": false
},
"tax_ids": [
{
"type": "<string>",
"value": "<string>",
"country": "<string>",
"verification_status": "<string>"
}
],
"metadata": {},
"labels": "<core.Labels>",
"invoice_settings": {},
"tax_exempt": "<string>",
"preferred_locales": [
"<string>"
],
"business_name": "<string>",
"currency": "<string>"
},
"invoice": null,
"payment_method": {
"id": "<string>",
"type": "<string>",
"brand": "<string>",
"issuer": "<string>",
"last4": "<string>",
"object": "<string>",
"livemode": false,
"created_at": null,
"updated_at": null,
"customer_id": "<string>",
"card_holder_name": "<string>",
"fingerprint": "<string>",
"exp_month": 0,
"exp_year": 0,
"card": {
"brand": "<string>",
"issuer": "<string>",
"last4": "<string>",
"exp_month": 0,
"exp_year": 0
},
"billing_details": {},
"allow_redisplay": "<string>",
"reference_id": "<string>",
"provider": "<string>",
"metadata": {},
"labels": "<core.Labels>",
"customer": {
"id": "<string>",
"object": "<string>",
"livemode": false,
"created_at": null,
"updated_at": null,
"name": "<string>",
"email": "<string>",
"phone": "<string>",
"address": {
"city": "<string>",
"country": "<string>",
"line1": "<string>",
"line2": "<string>",
"postal_code": "<string>",
"state": "<string>"
},
"shipping": {
"name": "<string>",
"phone": "<string>",
"address": {
"city": "<string>",
"country": "<string>",
"line1": "<string>",
"line2": "<string>",
"postal_code": "<string>",
"state": "<string>"
}
},
"is_system": false,
"is_application_customer": false,
"capabilities": {
"charge": false,
"transfer": false,
"payout": false
},
"tax_ids": [
{
"type": "<string>",
"value": "<string>",
"country": "<string>",
"verification_status": "<string>"
}
],
"metadata": {},
"labels": "<core.Labels>",
"invoice_settings": {},
"tax_exempt": "<string>",
"preferred_locales": [
"<string>"
],
"business_name": "<string>",
"currency": "<string>"
},
"provider_connection_status": "<string>",
"needs_recollection": false
},
"balance": {
"id": "<string>",
"object": "<string>",
"livemode": false,
"created_at": null,
"updated_at": null,
"customer_id": "<string>",
"account": "<string>",
"currency": "<string>",
"name": "<string>",
"available": 0,
"hold": 0,
"scaling_factor": 0,
"description": "<string>",
"customer": {
"id": "<string>",
"object": "<string>",
"livemode": false,
"created_at": null,
"updated_at": null,
"name": "<string>",
"email": "<string>",
"phone": "<string>",
"address": {
"city": "<string>",
"country": "<string>",
"line1": "<string>",
"line2": "<string>",
"postal_code": "<string>",
"state": "<string>"
},
"shipping": {
"name": "<string>",
"phone": "<string>",
"address": {
"city": "<string>",
"country": "<string>",
"line1": "<string>",
"line2": "<string>",
"postal_code": "<string>",
"state": "<string>"
}
},
"is_system": false,
"is_application_customer": false,
"capabilities": {
"charge": false,
"transfer": false,
"payout": false
},
"tax_ids": [
{
"type": "<string>",
"value": "<string>",
"country": "<string>",
"verification_status": "<string>"
}
],
"metadata": {},
"labels": "<core.Labels>",
"invoice_settings": {},
"tax_exempt": "<string>",
"preferred_locales": [
"<string>"
],
"business_name": "<string>",
"currency": "<string>"
}
}
},
"refund_application_fee": false,
"reverse_transfer": false,
"transfer_reversal": "<string>",
"application_fee_refund": "<string>"
}400400 Bad Request
Headers
| Name | Value |
|---|---|
| Content-Type | application/json |
Body
{
"object": "error",
"code": "<string>",
"key": "<string>",
"i18n_key": "<string>",
"message": "<string>",
"request_id": "<string>"
}