// api reference

Payments

GETList payments, newest first
GETRetrieve a payment
PATCHReplace a payment's metadata
POSTTry a failed release of the seller's share again
GETList refunds, newest first
POSTRefund a payment, in full or in part
GETRetrieve a refund
PATCHReplace a refund's metadata

GET /v1/payments

List payments, newest first

secret key only

GET /v1/paymentsrequest

curl https://api.marketsdk.com/v1/payments \
  -H "Authorization: Bearer $MARKETSDK_KEY"

200 example response, payment list

{
  "object": "list",
  "data": [
    {
      "object": "payment",
      "id": "pay_034XtPDs7UJ0TXzTsdaHZa",
      "order": "string",
      "method": "checkout_session",
      "status": "awaiting_payment",
      "amount": 0,
      "fee_amount": 0,
      "currency": "USD",
      "checkout_url": null,
      "client_secret": null,
      "last_failure": null,
      "amount_refunded": 0,
      "release": {
        "status": "held",
        "amount": 0,
        "amount_reversed": 0,
        "failure": null,
        "released_at": null
      },
      "stripe": {
        "payment_intent": null,
        "checkout_session": null,
        "charge": null,
        "transfer": null
      },
      "metadata": {},
      "paid_at": null,
      "canceled_at": null,
      "created_at": "2026-10-01T12:00:00.000Z",
      "updated_at": "2026-10-01T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

parameters

Parameters
field	type	about
limit	integer, in query	min 1, max 100, default 20
starting_after	string, in query	The `next_cursor` of the previous page.
order	string, in query	Only the payment for this order.
status	one of: awaiting_payment, succeeded, canceled, in query

returns 200, payment list

fields

Response fields
field	type	about
objectrequired	one of: list
datarequired	array of payment
data[].objectrequired	one of: payment
data[].idrequired	string
data[].orderrequired	string
data[].methodrequired	one of: checkout_session, payment_intent
data[].statusrequired	one of: awaiting_payment, succeeded, canceled
data[].amountrequired	integer	Minor units.
data[].fee_amountrequired	integer	The customer's platform fee. Minor units.
data[].currencyrequired	string
data[].checkout_urlrequired	string or null	Stripe-hosted checkout. Shown only while payment is due.
data[].client_secretrequired	string or null	For Stripe Elements on your own page. Shown only while payment is due.
data[].last_failurerequired	string or null	Stripe's message for the last failed attempt to pay.
data[].amount_refundedrequired	integer	Refunded or being refunded. Minor units.
data[].releaserequired	payment release
data[].release.statusrequired	one of: held, releasing, released, failed, nothing_to_release, null or null	Null until the buyer pays.
data[].release.amountrequired	integer	Transferred to the seller's Stripe account. Minor units.
data[].release.amount_reversedrequired	integer	Taken back from the seller for refunds after release. Minor units.
data[].release.failurerequired	string or null
data[].release.released_atrequired	timestamp or null
data[].striperequired	payment stripe	Ids of the objects on your Stripe account.
data[].stripe.payment_intentrequired	string or null
data[].stripe.checkout_sessionrequired	string or null
data[].stripe.chargerequired	string or null
data[].stripe.transferrequired	string or null
data[].metadatarequired	object of strings
data[].paid_atrequired	timestamp or null
data[].canceled_atrequired	timestamp or null
data[].created_atrequired	timestamp
data[].updated_atrequired	timestamp
has_morerequired	boolean	Whether another page follows.
next_cursorrequired	string or null	Pass as `starting_after` (or `cursor` for search) to get the next page.

errors

400The request is not valid.
401No API key, or not a valid one.
429Rate limited. See Retry-After.

GET /v1/payments/{id}

Retrieve a payment

secret key only

GET /v1/payments/{id}request

curl https://api.marketsdk.com/v1/payments/{id} \
  -H "Authorization: Bearer $MARKETSDK_KEY"

200 example response, payment

{
  "object": "payment",
  "id": "pay_034XtPDs7UJ0TXzTsdaHZa",
  "order": "string",
  "method": "checkout_session",
  "status": "awaiting_payment",
  "amount": 0,
  "fee_amount": 0,
  "currency": "USD",
  "checkout_url": null,
  "client_secret": null,
  "last_failure": null,
  "amount_refunded": 0,
  "release": {
    "status": "held",
    "amount": 0,
    "amount_reversed": 0,
    "failure": null,
    "released_at": null
  },
  "stripe": {
    "payment_intent": null,
    "checkout_session": null,
    "charge": null,
    "transfer": null
  },
  "metadata": {},
  "paid_at": null,
  "canceled_at": null,
  "created_at": "2026-10-01T12:00:00.000Z",
  "updated_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

returns 200, payment

fields

Response fields
field	type	about
objectrequired	one of: payment
idrequired	string
orderrequired	string
methodrequired	one of: checkout_session, payment_intent
statusrequired	one of: awaiting_payment, succeeded, canceled
amountrequired	integer	Minor units.
fee_amountrequired	integer	The customer's platform fee. Minor units.
currencyrequired	string
checkout_urlrequired	string or null	Stripe-hosted checkout. Shown only while payment is due.
client_secretrequired	string or null	For Stripe Elements on your own page. Shown only while payment is due.
last_failurerequired	string or null	Stripe's message for the last failed attempt to pay.
amount_refundedrequired	integer	Refunded or being refunded. Minor units.
releaserequired	payment release
release.statusrequired	one of: held, releasing, released, failed, nothing_to_release, null or null	Null until the buyer pays.
release.amountrequired	integer	Transferred to the seller's Stripe account. Minor units.
release.amount_reversedrequired	integer	Taken back from the seller for refunds after release. Minor units.
release.failurerequired	string or null
release.released_atrequired	timestamp or null
striperequired	payment stripe	Ids of the objects on your Stripe account.
stripe.payment_intentrequired	string or null
stripe.checkout_sessionrequired	string or null
stripe.chargerequired	string or null
stripe.transferrequired	string or null
metadatarequired	object of strings
paid_atrequired	timestamp or null
canceled_atrequired	timestamp or null
created_atrequired	timestamp
updated_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
429Rate limited. See Retry-After.

PATCH /v1/payments/{id}

Replace a payment's metadata

secret key only

PATCH /v1/payments/{id}request

curl -X PATCH https://api.marketsdk.com/v1/payments/{id} \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata":{}}'

200 example response, payment

{
  "object": "payment",
  "id": "pay_034XtPDs7UJ0TXzTsdaHZa",
  "order": "string",
  "method": "checkout_session",
  "status": "awaiting_payment",
  "amount": 0,
  "fee_amount": 0,
  "currency": "USD",
  "checkout_url": null,
  "client_secret": null,
  "last_failure": null,
  "amount_refunded": 0,
  "release": {
    "status": "held",
    "amount": 0,
    "amount_reversed": 0,
    "failure": null,
    "released_at": null
  },
  "stripe": {
    "payment_intent": null,
    "checkout_session": null,
    "charge": null,
    "transfer": null
  },
  "metadata": {},
  "paid_at": null,
  "canceled_at": null,
  "created_at": "2026-10-01T12:00:00.000Z",
  "updated_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

body, update metadata

Request body
field	type	about
metadatarequired	object of strings

returns 200, payment

fields

Response fields
field	type	about
objectrequired	one of: payment
idrequired	string
orderrequired	string
methodrequired	one of: checkout_session, payment_intent
statusrequired	one of: awaiting_payment, succeeded, canceled
amountrequired	integer	Minor units.
fee_amountrequired	integer	The customer's platform fee. Minor units.
currencyrequired	string
checkout_urlrequired	string or null	Stripe-hosted checkout. Shown only while payment is due.
client_secretrequired	string or null	For Stripe Elements on your own page. Shown only while payment is due.
last_failurerequired	string or null	Stripe's message for the last failed attempt to pay.
amount_refundedrequired	integer	Refunded or being refunded. Minor units.
releaserequired	payment release
release.statusrequired	one of: held, releasing, released, failed, nothing_to_release, null or null	Null until the buyer pays.
release.amountrequired	integer	Transferred to the seller's Stripe account. Minor units.
release.amount_reversedrequired	integer	Taken back from the seller for refunds after release. Minor units.
release.failurerequired	string or null
release.released_atrequired	timestamp or null
striperequired	payment stripe	Ids of the objects on your Stripe account.
stripe.payment_intentrequired	string or null
stripe.checkout_sessionrequired	string or null
stripe.chargerequired	string or null
stripe.transferrequired	string or null
metadatarequired	object of strings
paid_atrequired	timestamp or null
canceled_atrequired	timestamp or null
created_atrequired	timestamp
updated_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
429Rate limited. See Retry-After.

POST /v1/payments/{id}/retry_release

Try a failed release of the seller's share again

For a release that failed, for example because the seller could not yet receive transfers. A release is also tried again by itself when the seller becomes able to receive payouts.

secret key only

POST /v1/payments/{id}/retry_releaserequest

curl -X POST https://api.marketsdk.com/v1/payments/{id}/retry_release \
  -H "Authorization: Bearer $MARKETSDK_KEY"

200 example response, payment

{
  "object": "payment",
  "id": "pay_034XtPDs7UJ0TXzTsdaHZa",
  "order": "string",
  "method": "checkout_session",
  "status": "awaiting_payment",
  "amount": 0,
  "fee_amount": 0,
  "currency": "USD",
  "checkout_url": null,
  "client_secret": null,
  "last_failure": null,
  "amount_refunded": 0,
  "release": {
    "status": "held",
    "amount": 0,
    "amount_reversed": 0,
    "failure": null,
    "released_at": null
  },
  "stripe": {
    "payment_intent": null,
    "checkout_session": null,
    "charge": null,
    "transfer": null
  },
  "metadata": {},
  "paid_at": null,
  "canceled_at": null,
  "created_at": "2026-10-01T12:00:00.000Z",
  "updated_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

returns 200, payment

fields

Response fields
field	type	about
objectrequired	one of: payment
idrequired	string
orderrequired	string
methodrequired	one of: checkout_session, payment_intent
statusrequired	one of: awaiting_payment, succeeded, canceled
amountrequired	integer	Minor units.
fee_amountrequired	integer	The customer's platform fee. Minor units.
currencyrequired	string
checkout_urlrequired	string or null	Stripe-hosted checkout. Shown only while payment is due.
client_secretrequired	string or null	For Stripe Elements on your own page. Shown only while payment is due.
last_failurerequired	string or null	Stripe's message for the last failed attempt to pay.
amount_refundedrequired	integer	Refunded or being refunded. Minor units.
releaserequired	payment release
release.statusrequired	one of: held, releasing, released, failed, nothing_to_release, null or null	Null until the buyer pays.
release.amountrequired	integer	Transferred to the seller's Stripe account. Minor units.
release.amount_reversedrequired	integer	Taken back from the seller for refunds after release. Minor units.
release.failurerequired	string or null
release.released_atrequired	timestamp or null
striperequired	payment stripe	Ids of the objects on your Stripe account.
stripe.payment_intentrequired	string or null
stripe.checkout_sessionrequired	string or null
stripe.chargerequired	string or null
stripe.transferrequired	string or null
metadatarequired	object of strings
paid_atrequired	timestamp or null
canceled_atrequired	timestamp or null
created_atrequired	timestamp
updated_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
409The object is not in a state that allows this.
429Rate limited. See Retry-After.

GET /v1/refunds

List refunds, newest first

secret key only

GET /v1/refundsrequest

curl https://api.marketsdk.com/v1/refunds \
  -H "Authorization: Bearer $MARKETSDK_KEY"

200 example response, refund list

{
  "object": "list",
  "data": [
    {
      "object": "refund",
      "id": "ref_034XtPDs7UJ0TXzTsdaHZa",
      "payment": "string",
      "order": "string",
      "amount": 0,
      "currency": "USD",
      "reason": "requested_by_customer",
      "initiated_by": "api",
      "status": "pending",
      "failure_reason": null,
      "transfer_reversal": {
        "amount": 0
      },
      "stripe": {
        "refund": null,
        "transfer_reversal": null
      },
      "metadata": {},
      "created_at": "2026-10-01T12:00:00.000Z",
      "updated_at": "2026-10-01T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

parameters

Parameters
field	type	about
limit	integer, in query	min 1, max 100, default 20
starting_after	string, in query	The `next_cursor` of the previous page.
payment	string, in query
order	string, in query

returns 200, refund list

fields

Response fields
field	type	about
objectrequired	one of: list
datarequired	array of refund
data[].objectrequired	one of: refund
data[].idrequired	string
data[].paymentrequired	string
data[].orderrequired	string
data[].amountrequired	integer	Minor units.
data[].currencyrequired	string
data[].reasonrequired	one of: requested_by_customer, duplicate, fraudulent, null or null
data[].initiated_byrequired	one of: api, order_cancelled, order_expired, late_payment, stripe	`api` for a refund you asked for; `order_cancelled` and `order_expired` when an order ended without completing; `late_payment` for a payment that arrived after its order lapsed; `stripe` for a refund made in the Stripe dashboard, which does not reverse the transfer.
data[].statusrequired	one of: pending, succeeded, failed, canceled
data[].failure_reasonrequired	string or null
data[].transfer_reversalrequired	refund reversal or null	Present when the refund came after release.
data[].transfer_reversal.amountrequired	integer	Taken back from the seller's transfer. Minor units.
data[].striperequired	refund stripe
data[].stripe.refundrequired	string or null
data[].stripe.transfer_reversalrequired	string or null
data[].metadatarequired	object of strings
data[].created_atrequired	timestamp
data[].updated_atrequired	timestamp
has_morerequired	boolean	Whether another page follows.
next_cursorrequired	string or null	Pass as `starting_after` (or `cursor` for search) to get the next page.

errors

400The request is not valid.
401No API key, or not a valid one.
429Rate limited. See Retry-After.

POST /v1/refunds

Refund a payment, in full or in part

Recorded at once with status pending, then made at Stripe. If the seller's share was already released, the transfer is reversed in the same proportion, so your fee is given back in proportion too.

secret key only

POST /v1/refundsrequest

curl -X POST https://api.marketsdk.com/v1/refunds \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

201 example response, refund

{
  "object": "refund",
  "id": "ref_034XtPDs7UJ0TXzTsdaHZa",
  "payment": "string",
  "order": "string",
  "amount": 0,
  "currency": "USD",
  "reason": "requested_by_customer",
  "initiated_by": "api",
  "status": "pending",
  "failure_reason": null,
  "transfer_reversal": {
    "amount": 0
  },
  "stripe": {
    "refund": null,
    "transfer_reversal": null
  },
  "metadata": {},
  "created_at": "2026-10-01T12:00:00.000Z",
  "updated_at": "2026-10-01T12:00:00.000Z"
}

body, create refund

Request body
field	type	about
payment	string	The payment to refund. Give this or `order`.
order	string	The order whose payment to refund. Give this or `payment`.
amount	integer	Minor units. Defaults to everything not yet refunded.min 1
reason	one of: requested_by_customer, duplicate, fraudulent
metadata	object of strings

returns 201, refund

fields

Response fields
field	type	about
objectrequired	one of: refund
idrequired	string
paymentrequired	string
orderrequired	string
amountrequired	integer	Minor units.
currencyrequired	string
reasonrequired	one of: requested_by_customer, duplicate, fraudulent, null or null
initiated_byrequired	one of: api, order_cancelled, order_expired, late_payment, stripe	`api` for a refund you asked for; `order_cancelled` and `order_expired` when an order ended without completing; `late_payment` for a payment that arrived after its order lapsed; `stripe` for a refund made in the Stripe dashboard, which does not reverse the transfer.
statusrequired	one of: pending, succeeded, failed, canceled
failure_reasonrequired	string or null
transfer_reversalrequired	refund reversal or null	Present when the refund came after release.
transfer_reversal.amountrequired	integer	Taken back from the seller's transfer. Minor units.
striperequired	refund stripe
stripe.refundrequired	string or null
stripe.transfer_reversalrequired	string or null
metadatarequired	object of strings
created_atrequired	timestamp
updated_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
409The object is not in a state that allows this.
429Rate limited. See Retry-After.

GET /v1/refunds/{id}

Retrieve a refund

secret key only

GET /v1/refunds/{id}request

curl https://api.marketsdk.com/v1/refunds/{id} \
  -H "Authorization: Bearer $MARKETSDK_KEY"

200 example response, refund

{
  "object": "refund",
  "id": "ref_034XtPDs7UJ0TXzTsdaHZa",
  "payment": "string",
  "order": "string",
  "amount": 0,
  "currency": "USD",
  "reason": "requested_by_customer",
  "initiated_by": "api",
  "status": "pending",
  "failure_reason": null,
  "transfer_reversal": {
    "amount": 0
  },
  "stripe": {
    "refund": null,
    "transfer_reversal": null
  },
  "metadata": {},
  "created_at": "2026-10-01T12:00:00.000Z",
  "updated_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

returns 200, refund

fields

Response fields
field	type	about
objectrequired	one of: refund
idrequired	string
paymentrequired	string
orderrequired	string
amountrequired	integer	Minor units.
currencyrequired	string
reasonrequired	one of: requested_by_customer, duplicate, fraudulent, null or null
initiated_byrequired	one of: api, order_cancelled, order_expired, late_payment, stripe	`api` for a refund you asked for; `order_cancelled` and `order_expired` when an order ended without completing; `late_payment` for a payment that arrived after its order lapsed; `stripe` for a refund made in the Stripe dashboard, which does not reverse the transfer.
statusrequired	one of: pending, succeeded, failed, canceled
failure_reasonrequired	string or null
transfer_reversalrequired	refund reversal or null	Present when the refund came after release.
transfer_reversal.amountrequired	integer	Taken back from the seller's transfer. Minor units.
striperequired	refund stripe
stripe.refundrequired	string or null
stripe.transfer_reversalrequired	string or null
metadatarequired	object of strings
created_atrequired	timestamp
updated_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
429Rate limited. See Retry-After.

PATCH /v1/refunds/{id}

Replace a refund's metadata

secret key only

PATCH /v1/refunds/{id}request

curl -X PATCH https://api.marketsdk.com/v1/refunds/{id} \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata":{}}'

200 example response, refund

{
  "object": "refund",
  "id": "ref_034XtPDs7UJ0TXzTsdaHZa",
  "payment": "string",
  "order": "string",
  "amount": 0,
  "currency": "USD",
  "reason": "requested_by_customer",
  "initiated_by": "api",
  "status": "pending",
  "failure_reason": null,
  "transfer_reversal": {
    "amount": 0
  },
  "stripe": {
    "refund": null,
    "transfer_reversal": null
  },
  "metadata": {},
  "created_at": "2026-10-01T12:00:00.000Z",
  "updated_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

body, update metadata

Request body
field	type	about
metadatarequired	object of strings

returns 200, refund

fields

Response fields
field	type	about
objectrequired	one of: refund
idrequired	string
paymentrequired	string
orderrequired	string
amountrequired	integer	Minor units.
currencyrequired	string
reasonrequired	one of: requested_by_customer, duplicate, fraudulent, null or null
initiated_byrequired	one of: api, order_cancelled, order_expired, late_payment, stripe	`api` for a refund you asked for; `order_cancelled` and `order_expired` when an order ended without completing; `late_payment` for a payment that arrived after its order lapsed; `stripe` for a refund made in the Stripe dashboard, which does not reverse the transfer.
statusrequired	one of: pending, succeeded, failed, canceled
failure_reasonrequired	string or null
transfer_reversalrequired	refund reversal or null	Present when the refund came after release.
transfer_reversal.amountrequired	integer	Taken back from the seller's transfer. Minor units.
striperequired	refund stripe
stripe.refundrequired	string or null
stripe.transfer_reversalrequired	string or null
metadatarequired	object of strings
created_atrequired	timestamp
updated_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
429Rate limited. See Retry-After.