Skip to content
Paymee Developers

Refund a payment session

POST
/gateway/sessions/{session_id}/refund/
curl --request POST \
  --url https://api.paymee.online/api/v1/gateway/sessions/example/refund/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "reason": "Customer requested a refund", "refund_type": "FULL" }'

Issue a full or partial refund against a succeeded payment session. For PARTIAL refunds, amount is required. The response is the refund: SUCCEEDED when the acquirer confirmed it, PENDING when it is completed manually (refund.succeeded / refund.failed follow). Send an Idempotency-Key to retry safely.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
session_id
required
string

Prefixed public id of the payment session (e.g. ps_...).

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
string

A unique value you generate per refund (e.g. a UUID v4), up to 255 characters. Repeating a request with the same key returns the refund it created (header Idempotent-Replayed: true) instead of refunding again; reusing it for a different request is a 409 idempotency-key-reuse. Keys do not expire.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

A refund request on the merchant API (sk_ keys).

reopen_invoice is a merchant-portal option (invoices are a portal feature), so the API neither takes nor documents it.

object
reason
required
string
>= 1 characters <= 500 characters
refund_type
  • FULL - FULL
  • PARTIAL - PARTIAL
string
default: FULL
Allowed values: FULL PARTIAL
amount

Required for partial refunds. A positive decimal string in the payment’s currency, e.g. “3.000”.

string
>= 1 characters
metadata
Examples

Full refund

{
  "reason": "Customer requested a refund",
  "refund_type": "FULL"
}

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json

A refund.

object
id
required

Refund id (re_…).

string
session_id
required

The refunded payment session (ps_…).

string
merchant_reference
required

The session’s merchant_reference.

string
amount
required

Refunded amount, as a decimal string.

string
currency
required

ISO 4217 currency of amount.

string
refund_type
  • FULL - Full
  • PARTIAL - Partial
string
Allowed values: FULL PARTIAL
status
required

PENDING while the refund is in progress, SUCCEEDED once the money is returned, FAILED if it was not.

string
Allowed values: PENDING SUCCEEDED FAILED
reason
Refund reason
string
processor_message
required

Why the refund is pending or failed, when known. Informational; may change.

string | null
created_at
required
string format: date-time
completed_at
required

When the refund reached SUCCEEDED or FAILED.

string | null
Example
{
  "refund_type": "FULL",
  "status": "PENDING"
}

400

Section titled “400”

Malformed request: the body is not valid JSON, or a header is invalid.

Media typeapplication/problem+json

RFC 9457 problem detail body (application/problem+json).

object
type
required

URI identifying the error type.

string format: uri
title
required

Short, human-readable summary of the error type.

string
status
required

HTTP status code.

integer
detail
required

Human-readable explanation specific to this occurrence.

string
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example"
}

401

Section titled “401”

Missing, malformed, expired, or revoked API key.

Media typeapplication/problem+json

RFC 9457 problem detail body (application/problem+json).

object
type
required

URI identifying the error type.

string format: uri
title
required

Short, human-readable summary of the error type.

string
status
required

HTTP status code.

integer
detail
required

Human-readable explanation specific to this occurrence.

string
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example"
}

404

Section titled “404”

The payment session does not exist for this merchant account.

Media typeapplication/problem+json

RFC 9457 problem detail body (application/problem+json).

object
type
required

URI identifying the error type.

string format: uri
title
required

Short, human-readable summary of the error type.

string
status
required

HTTP status code.

integer
detail
required

Human-readable explanation specific to this occurrence.

string
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example"
}

409

Section titled “409”

The request conflicts with an earlier one; the type says how.

Media typeapplication/problem+json

Problem detail of a 409.

object
type
required

URI identifying the error type.

string format: uri
title
required

Short, human-readable summary of the error type.

string
status
required

HTTP status code.

integer
detail
required

Human-readable explanation specific to this occurrence.

string
existing_session_id

On a conflict from session creation: the session that already uses this merchant_reference.

string
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "existing_session_id": "example"
}

422

Section titled “422”

A field failed validation (errors lists them), or a business rule refused the request (the type says which).

Media typeapplication/problem+json

Problem detail of a 422: a per-field errors array when fields failed validation; no errors when a business rule refused the request (the type says which).

object
type
required

URI identifying the error type.

string format: uri
title
required

Short, human-readable summary of the error type.

string
status
required

HTTP status code.

integer
detail
required

Human-readable explanation specific to this occurrence.

string
errors
Array<object>

A single field-level validation error inside a problem+json body.

object
field
required

Name of the field that failed validation.

string
code
required

Machine-readable error code, e.g. ‘required’.

string
message
required

Human-readable description of the failure.

string
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "errors": [
    {
      "field": "example",
      "code": "example",
      "message": "example"
    }
  ]
}

429

Section titled “429”

Rate limit exceeded. Wait the number of seconds in the Retry-After header.

Media typeapplication/problem+json

RFC 9457 problem detail body (application/problem+json).

object
type
required

URI identifying the error type.

string format: uri
title
required

Short, human-readable summary of the error type.

string
status
required

HTTP status code.

integer
detail
required

Human-readable explanation specific to this occurrence.

string
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example"
}

500

Section titled “500”

Unexpected error; nothing was changed. Safe to retry with backoff.

Media typeapplication/problem+json

RFC 9457 problem detail body (application/problem+json).

object
type
required

URI identifying the error type.

string format: uri
title
required

Short, human-readable summary of the error type.

string
status
required

HTTP status code.

integer
detail
required

Human-readable explanation specific to this occurrence.

string
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example"
}