Refunds

Refunds are a reversal of a prior Transaction. For some Payment Providers, and some Payment Methods, the original transaction may provide a mechanism for refunding, and in other cases a new transaction may be created to process the refund.

Data Types

RefundResponse

Key	Value
type	refunds
id	UUID
Attributes
amount	Integer
memo	String
status	String
metadata	Metadata
created-at	Timestamp
updated-at	Timestamp
Relationships
transaction	TransactionRelationship

RefundResponse Example

{
  "data": {
    "id": "4c72784e-fb2a-4858-8067-95b6e36d54c0",
    "type": "refunds",
    "attributes": {
      "amount": 1000,
      "memo": "Refund for order #12345",
      "status": "processed",
      "metadata": {
        "order_id": "12345"
      },
      "created-at": "2024-05-01T12:00:00Z",
      "updated-at": "2024-05-01T12:00:00Z"
    },
    "relationships": {
      "transaction": {
        "data": {
          "id": "1234567890",
          "type": "transactions"
        }
      }
    }
  }
}

RefundRequest

Key	Value
type	refunds	Required
Attributes
amount	Integer	Required
memo	String	Required
metadata	Metadata
Relationships
transaction	TransactionRelationship	Required

If your processing gateway supports it, you may create multiple partial refunds up to the original transaction total

RefundRequest Example

{
  "data": {
    "type": "refunds",
    "attributes": {
      "amount": 1000,
      "memo": "Refund for order #12345",
      "metadata": {
        "order_id": "12345"
      }
    },
    "relationships": {
      "transaction": {
        "data": {
          "id": "{TRANSACTION_ID}",
          "type": "transactions"
        }
      }
    }
  }
}

This endpoint retrieves a paginated list of Refunds. By default, a maximum of thirty Refunds are shown per page.

This endpoint returns an array of RefundResponse objects.

Request

GET

/v1/refunds

  curl --request GET \
        --url 'https://api.opentransact.com/v1/refunds' \
        --header 'Authorization: Basic {API_KEY}' \
        --header 'Content-Type: application/vnd.api+json'

Response

{
  "data": [
    {
      "id": "4c72784e-fb2a-4858-8067-95b6e36d54c0",
      "type": "refunds",
      "attributes": {
        "amount": 1000,
        "memo": "Refund for order #12345",
        "status": "processed",
        "metadata": {
          "order_id": "12345"
        },
        "created-at": "2024-05-01T12:00:00Z",
        "updated-at": "2024-05-01T12:00:00Z"
      },
      "relationships": {
        "transaction": {
          "data": {
            "id": "1234567890",
            "type": "transactions"
          }
        }
      }
    },
    ... // Additional refunds
  ],
  "meta": {
    "count": 100,
    "current-page": 2,
    "page-count": 4
  },
  "links": {
    "self": "https://api.opentransact.com/v1/refunds?page[number]=2&page[size]=30",
    "first": "https://api.opentransact.com/v1/refunds?page[number]=1&page[size]=30",
    "last": "https://api.opentransact.com/v1/refunds?page[number]=4&page[size]=30",
    "next": "https://api.opentransact.com/v1/refunds?page[number]=2&page[size]=30",
    "prev": "https://api.opentransact.com/v1/refunds?page[number]=1&page[size]=30"
  }
}

POST/v1/refunds

Create a Refund

This endpoint creates a new Refund in OpenTransact.

This endpoint accepts a RefundRequest object and returns a RefundResponse object.

Request

POST

/v1/refunds

  curl --request POST \
        --url https://api.opentransact.com/v1/refunds \
        --header 'Authorization: Basic {API_KEY}' \
        --header 'Content-Type: application/vnd.api+json' \
        --data '{
                  "data": {
                    "type": "refunds",
                    "attributes": {
                      "amount": 52,
                      "memo": "Test Transaction Refund"
                    },
                    "relationships": {
                      "transaction": {
                        "data": {
                          "id": "{TRANSACTION_ID}",
                          "type": "transactions"
                        }
                      }
                    }
                  }
                }'

Response

{
  "data": {
    "id": "4c72784e-fb2a-4858-8067-95b6e36d54c0",
    "type": "refunds",
    "attributes": {
      "amount": 52,
      "memo": "Test Transaction Refund",
      "status": "processed",
      "metadata": {
        "order_id": "12345"
      },
      "created-at": "2024-05-01T12:00:00Z",
      "updated-at": "2024-05-01T12:00:00Z"
    },
    "relationships": {
      "transaction": {
        "data": {
          "id": "1234567890",
          "type": "transactions"
        }
      }
    }
  }
}

GET/v1/refunds/:id

Show a Refund

This endpoint retrieves a Refund by providing its ID.

This endpoint returns a RefundResponse object.

Request

GET

/v1/refunds/:id

    curl --request GET \
        --url https://api.opentransact.com/v1/refunds/{REFUND_ID} \
        --header 'Authorization: Basic {API_KEY}' \
        --header 'Content-Type: application/vnd.api+json'

Response

{
  "data": {
    "id": "4c72784e-fb2a-4858-8067-95b6e36d54c0",
    "type": "refunds",
    "attributes": {
      "amount": 52,
      "memo": "Test Transaction Refund",
      "status": "processed",
      "metadata": {
        "order_id": "12345"
      },
      "created-at": "2024-05-01T12:00:00Z",
      "updated-at": "2024-05-01T12:00:00Z"
    }
  },
  "relationships": {
    "transaction": {
      "data": {
        "id": "1234567890",
        "type": "transactions"
      }
    }
  }
}