Pin Payments MCP by usefulapi

The current Pin Payments account balance: available (ready to transfer) and pending (available plus estimated funds from charges that have not settled yet), per currency, in the currency's base unit (cents for AUD). GET /balance.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List charges (card payments), 25 per page: amount (in the currency's base unit, e.g. cents for AUD), currency, description, payer email, status_message/success, total_fees, merchant_entitlement, amount_refunded, captured, settlement transfers, chargebacks flag, metadata. The card is shown only as scheme and last four digits. GET /charges.

{
  "type": "object",
  "properties": {
    "page": {
      "description": "Page number, from 1 (default 1); 25 results per page. Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Search charges by free text (description, email, metadata, cardholder name, currency, exact amount in the currency's base unit, exact charge/card/refund/customer token) and/or a created-date range. GET /charges/search.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Text to match.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "start_date": {
      "description": "Created on or after this date, yyyy-mm-dd.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "end_date": {
      "description": "Created before this date, yyyy-mm-dd.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "sort": {
      "description": "Sort field (default created_at).",
      "type": "string",
      "enum": [
        "created_at",
        "amount"
      ]
    },
    "direction": {
      "description": "Sort direction (default asc).",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    },
    "page": {
      "description": "Page number, from 1 (default 1); 25 results per page. Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One charge by token (ch_...), with fees, refunds total, settlement transfer state and chargeback flag. GET /charges/{token}.

{
  "type": "object",
  "properties": {
    "charge_token": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Charge token, e.g. ch_lfUYEBK14zotCTykezJkfg."
    }
  },
  "required": [
    "charge_token"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

All refunds issued against one charge. GET /charges/{token}/refunds.

{
  "type": "object",
  "properties": {
    "charge_token": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Charge token (ch_...)."
    },
    "page": {
      "description": "Page number, from 1 (default 1); 25 results per page. Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    }
  },
  "required": [
    "charge_token"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List all refunds, 25 per page: amount (in the currency's base unit), currency, charge token, status_message, error_message, created_at. GET /refunds.

{
  "type": "object",
  "properties": {
    "page": {
      "description": "Page number, from 1 (default 1); 25 results per page. Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One refund by token (rf_...). GET /refunds/{token}.

{
  "type": "object",
  "properties": {
    "refund_token": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Refund token, e.g. rf_ERCQy--Ay6o-NKGiUVcKKA."
    }
  },
  "required": [
    "refund_token"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List card authorisations (held funds, not yet captured; they expire after seven days) with amount, amount_captured, amount_remaining and expired flags. GET /authorisations.

{
  "type": "object",
  "properties": {
    "page": {
      "description": "Page number, from 1 (default 1); 25 results per page. Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One authorisation by token (auth_...). GET /authorisations/{token}.

{
  "type": "object",
  "properties": {
    "authorisation_token": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Authorisation token, e.g. auth_NRzYklT8z3p0yiozsXEAIg."
    }
  },
  "required": [
    "authorisation_token"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List stored customers, 25 per page: token, email, first_name, last_name, phone_number, company, notes and the primary card as scheme and last four digits. GET /customers.

{
  "type": "object",
  "properties": {
    "page": {
      "description": "Page number, from 1 (default 1); 25 results per page. Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One customer by token (cus_...). GET /customers/{token}.

{
  "type": "object",
  "properties": {
    "customer_token": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Customer token, e.g. cus_XZg1ULpWaROQCOT5PdwLkQ."
    }
  },
  "required": [
    "customer_token"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Charges made by one customer. GET /customers/{token}/charges.

{
  "type": "object",
  "properties": {
    "customer_token": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Customer token (cus_...)."
    },
    "page": {
      "description": "Page number, from 1 (default 1); 25 results per page. Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    }
  },
  "required": [
    "customer_token"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Cards stored for one customer, each shown only as scheme, last four digits and issuing country (no token, expiry or address). GET /customers/{token}/cards.

{
  "type": "object",
  "properties": {
    "customer_token": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Customer token (cus_...)."
    },
    "page": {
      "description": "Page number, from 1 (default 1); 25 results per page. Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    }
  },
  "required": [
    "customer_token"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Subscriptions of one customer: state, plan, next billing date, active interval, cancellation time. GET /customers/{token}/subscriptions.

{
  "type": "object",
  "properties": {
    "customer_token": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Customer token (cus_...)."
    },
    "page": {
      "description": "Page number, from 1 (default 1); 25 results per page. Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    }
  },
  "required": [
    "customer_token"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List deposits made to the account (amount, currency, bank narration, available_at). GET /deposits.

{
  "type": "object",
  "properties": {
    "page": {
      "description": "Page number, from 1 (default 1); 25 results per page. Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One deposit by token (dpo_...). GET /deposits/{token}.

{
  "type": "object",
  "properties": {
    "deposit_token": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Deposit token, e.g. dpo_Ts3YECK14zotCTykezRspu."
    }
  },
  "required": [
    "deposit_token"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List transfers (payouts to bank accounts), 25 per page: status, amount, debits/credits, paid_at, reference, line item count, bank account (masked) and recipient. GET /transfers.

{
  "type": "object",
  "properties": {
    "page": {
      "description": "Page number, from 1 (default 1); 25 results per page. Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Search transfers by token, description, amount or recipient details and/or a created-date range. GET /transfers/search.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Text to match.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "start_date": {
      "description": "Created on or after this date, yyyy-mm-dd.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "end_date": {
      "description": "Created before this date, yyyy-mm-dd.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "sort": {
      "description": "Sort field (the only option is paid_at, also the default).",
      "type": "string",
      "enum": [
        "paid_at"
      ]
    },
    "direction": {
      "description": "Sort direction (default asc).",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    },
    "page": {
      "description": "Page number, from 1 (default 1); 25 results per page. Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One transfer by token (tfer_...). GET /transfers/{token}.

{
  "type": "object",
  "properties": {
    "transfer_token": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Transfer token, e.g. tfer_lfUYEBK14zotCTykezJkfg."
    }
  },
  "required": [
    "transfer_token"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The ledger line items that make up one transfer (charge entitlements, fees, refunds, chargebacks). GET /transfers/{token}/line_items.

{
  "type": "object",
  "properties": {
    "transfer_token": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Transfer token (tfer_...)."
    },
    "page": {
      "description": "Page number, from 1 (default 1); 25 results per page. Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    }
  },
  "required": [
    "transfer_token"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List transfer recipients (name, email, masked bank account). GET /recipients.

{
  "type": "object",
  "properties": {
    "page": {
      "description": "Page number, from 1 (default 1); 25 results per page. Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One recipient by token (rp_...). GET /recipients/{token}.

{
  "type": "object",
  "properties": {
    "recipient_token": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Recipient token, e.g. rp_a98a4fafROQCOT5PdwLkQ."
    }
  },
  "required": [
    "recipient_token"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Transfers paid to one recipient. GET /recipients/{token}/transfers.

{
  "type": "object",
  "properties": {
    "recipient_token": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Recipient token (rp_...)."
    },
    "page": {
      "description": "Page number, from 1 (default 1); 25 results per page. Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    }
  },
  "required": [
    "recipient_token"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List chargeback disputes: category, status, amount, the disputed charge, evidence_required_by and the relevant evidence types. GET /disputes.

{
  "type": "object",
  "properties": {
    "sort": {
      "description": "Sort field.",
      "type": "string",
      "enum": [
        "received_at",
        "evidence_required_by",
        "amount"
      ]
    },
    "direction": {
      "description": "Sort direction (default asc).",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    },
    "page": {
      "description": "Page number, from 1 (default 1); 25 results per page. Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Search disputes by status or exact charge token, optionally filtered by status. GET /disputes/search.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Text to match (status, or an exact charge token); at least 3 characters.",
      "type": "string",
      "minLength": 3,
      "maxLength": 200
    },
    "status": {
      "description": "Dispute status, e.g. evidence_required.",
      "type": "string",
      "minLength": 1,
      "maxLength": 60
    },
    "sort": {
      "description": "Sort field.",
      "type": "string",
      "enum": [
        "received_at",
        "evidence_required_by",
        "amount"
      ]
    },
    "direction": {
      "description": "Sort direction (default asc).",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    },
    "page": {
      "description": "Page number, from 1 (default 1); 25 results per page. Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One dispute by token (dis_...). GET /disputes/{token}.

{
  "type": "object",
  "properties": {
    "dispute_token": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Dispute token, e.g. dis_JRs6Xgk4jMyF33yGijQ7Nw."
    }
  },
  "required": [
    "dispute_token"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The activity feed of one dispute (status changes, ledger entries such as chargeback fees and recoveries). GET /disputes/{token}/activity.

{
  "type": "object",
  "properties": {
    "dispute_token": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Dispute token (dis_...)."
    }
  },
  "required": [
    "dispute_token"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List subscription plans: name, amount, currency, interval, trial and setup amounts, subscription counts by state. GET /plans.

{
  "type": "object",
  "properties": {
    "page": {
      "description": "Page number, from 1 (default 1); 25 results per page. Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One plan by token (plan_...). GET /plans/{token}.

{
  "type": "object",
  "properties": {
    "plan_token": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Plan token, e.g. plan_ZyDee4HNeUHFHC4SpM2idg."
    }
  },
  "required": [
    "plan_token"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Subscriptions to one plan. GET /plans/{token}/subscriptions.

{
  "type": "object",
  "properties": {
    "plan_token": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Plan token (plan_...)."
    },
    "page": {
      "description": "Page number, from 1 (default 1); 25 results per page. Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    }
  },
  "required": [
    "plan_token"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List all subscriptions: state (trial, active, cancelling, cancelled), plan, customer, next_billing_date, active interval, cancelled_at. GET /subscriptions.

{
  "type": "object",
  "properties": {
    "page": {
      "description": "Page number, from 1 (default 1); 25 results per page. Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One subscription by token (sub_...). GET /subscriptions/{token}.

{
  "type": "object",
  "properties": {
    "subscription_token": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Subscription token, e.g. sub_bZWXhTzHooKpk9FZjQfzqQ."
    }
  },
  "required": [
    "subscription_token"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The ledger entries (credits and debits) of one subscription. GET /subscriptions/{token}/ledger.

{
  "type": "object",
  "properties": {
    "subscription_token": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Subscription token (sub_...)."
    },
    "page": {
      "description": "Page number, from 1 (default 1); 25 results per page. Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    }
  },
  "required": [
    "subscription_token"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The account's event log (charge.captured, refund.created, dispute.updated, ...), each with the affected record (cards masked). GET /events.

{
  "type": "object",
  "properties": {
    "page": {
      "description": "Page number, from 1 (default 1); 25 results per page. Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One event by token (evt_...). GET /events/{token}.

{
  "type": "object",
  "properties": {
    "event_token": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Event token, e.g. evt_12K4fafROQsdI5PdwLkX."
    }
  },
  "required": [
    "event_token"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}