Payments

Toolset payments, 14 tools.

RecordsCopy Anchor Link

paymentCopy Anchor Link

A payment on an order, with its captures and refunds. A payment is found through the order: get the order with include payments for its payment ids.

• Permission: orders.read
• Tools: payment_list, payment_get
• Sorts: created_at, updated_at

Filters on the list:

payment_providerCopy Anchor Link

A payment provider installed in the store; its id is what mark_paid and the order payments name. Which regions offer it is a setting a person makes.

• Permission: orders.read
• Tools: payment_provider_list

Filters on the list:

refund_reasonCopy Anchor Link

A reason a refund can be filed under; pass its id to payment_refund.

• Permission: orders.read
• Tools: refund_reason_list, refund_reason_get
• Sorts: created_at

Filters on the list:

ActionsCopy Anchor Link

order_credit_line_createCopy Anchor Link

Settle an order's pending difference with a credit line instead of a payment or refund.

Only valid while the order has a pending difference: a positive amount settles money the customer still owes, a negative one money owed back, and neither may exceed the difference. amount is in the order currency. reference says what the credit is for and reference_id points at it. Nothing is charged or paid out.

• Action key: order_credit_line.create
• Permission: orders.refund
• Approval: Always waits for a person to approve it.
• Effect: Changes the live store.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "order_id": "019bb3ef-6501-7dc3-a2e7-726e91520b7a",
  "amount": -1200,
  "reference": "refund",
  "reference_id": "refund_01J9"
}

payment_captureCopy Anchor Link

Capture an authorized payment, in full or in part.

Most card and wallet providers settle a payment once: they capture only everything still open, and a smaller amount is refused with payment_partial_capture_unsupported. Then capture in full and refund the difference instead.

• Action key: payment.capture
• Permission: orders.write
• Approval: Always waits for a person to approve it.
• Effect: Changes the live store.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example inputs:

{
  "payment_id": "019bb4b5-6430-7a01-8e17-6df1bfccb8e5"
}

{
  "payment_id": "019bb4b5-6430-7a01-8e17-6df1bfccb8e5",
  "amount": 4990
}

payment_collection_createCopy Anchor Link

Open a payment collection on an order for an amount still to be paid.

Nothing is charged: it only opens the amount for payment. Mark it paid with payment_mark_paid once the money arrived.

• Action key: payment_collection.create
• Permission: orders.write
• Approval: Always waits for a person to approve it.
• Effect: Changes the live store.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "order_id": "019bb3ef-6501-7dc3-a2e7-726e91520b7a",
  "amount": 4990
}

payment_collection_deleteCopy Anchor Link

Delete a payment collection that holds no payment yet.

• Action key: payment_collection.delete
• Permission: orders.write
• Approval: Always waits for a person to approve it.
• Effect: Changes the live store.
• Destructive: in compact mode it runs with run_destructive_action.
• Retries: safe to repeat with the same input.

Example input:

{
  "payment_collection_id": "019bb4e4-0993-7733-bdd6-6e58e38f7703"
}

payment_mark_paidCopy Anchor Link

Record an order's payment as received outside the store, e.g. a bank transfer.

Takes the payment collection id from the order (get the order with include payments). Nothing is charged; the payment is only recorded as paid.

• Action key: payment.mark_paid
• Permission: orders.write
• Approval: Always waits for a person to approve it.
• Effect: Changes the live store.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "payment_collection_id": "019bb4e4-0993-7733-bdd6-6e58e38f7703",
  "order_id": "019bb3ef-6501-7dc3-a2e7-726e91520b7a"
}

payment_refundCopy Anchor Link

Refund part or all of a captured payment.

Omit amount to refund everything not yet refunded. Amounts are in the payment currency. A dry run reports how much is still refundable without refunding anything; list reasons with refund_reason_list.

• Action key: payment.refund
• Permission: orders.refund
• Approval: Always waits for a person to approve it.
• Effect: Changes the live store.
• Destructive: in compact mode it runs with run_destructive_action.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.
• Dry run: supported, with dry_run set to true.

Example inputs:

{
  "payment_id": "019bb4b5-6430-7a01-8e17-6df1bfccb8e5"
}

{
  "payment_id": "019bb4b5-6430-7a01-8e17-6df1bfccb8e5",
  "amount": 1200,
  "note": "damaged on arrival"
}

refund_reason_createCopy Anchor Link

Add a reason a refund can be filed under.

• Action key: refund_reason.create
• Permission: orders.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes the live store.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "label": "Damaged on arrival",
  "code": "damaged"
}

refund_reason_deleteCopy Anchor Link

Delete a refund reason; refunds already filed under it keep their record.

• Action key: refund_reason.delete
• Permission: orders.write
• Approval: Always waits for a person to approve it.
• Effect: Changes the live store.
• Destructive: in compact mode it runs with run_destructive_action.
• Retries: safe to repeat with the same input.

Example input:

{
  "refund_reason_id": "019bb65c-0f78-7003-af13-95ac276a7aeb"
}

refund_reason_updateCopy Anchor Link

Change the label, code or description of a refund reason.

• Action key: refund_reason.update
• Permission: orders.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes the live store.
• Retries: safe to repeat with the same input.

Example input:

{
  "refund_reason_id": "019bb65c-0f78-7003-af13-95ac276a7aeb",
  "label": "Arrived damaged"
}