Organization API: Customer Portal: Credit
The 8 Organization API operations for credit.
Part of Customer Portal.
Operations
Section titled Operations| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/orgs/{org_slug}/portal/credit |
The customer's credit balance and credit history, newest first |
| POST | /api/v1/orgs/{org_slug}/portal/credit/topup/charge |
Charge a saved payment method and add credit to the customer's balance |
| POST | /api/v1/orgs/{org_slug}/portal/credit/topup/checkout |
Hosted checkout to buy USD credit for an org customer |
| POST | /api/v1/orgs/{org_slug}/portal/credit/topup/confirm-payment |
Add credit for a card payment the customer finished in the page |
| POST | /api/v1/orgs/{org_slug}/portal/credit/topup/pay-intent |
Create a Stripe PaymentIntent to add credit in the page |
| GET | /api/v1/orgs/{org_slug}/portal/credit/topup/pay-quote |
The card account and amount for adding credit in the page |
| POST | /api/v1/orgs/{org_slug}/portal/credit/topup/paypal-capture |
Capture PayPal order and credit org customer balance |
| POST | /api/v1/orgs/{org_slug}/portal/credit/topup/square-pay |
Add credit with a Square card token, in one request |
The customer's credit balance and credit history, newest first
Section titled The customer's credit balance and credit history, newest firstGET /api/v1/orgs/{org_slug}/portal/credit
The customer's credit balance and credit history, newest first.
balance, balance_usd and every history amount are in credit_currency,
always USD. currency repeats it. The currency the customer pays in is
preferred_payment_currency at GET .../portal/payment-preference.
Parameters
Section titled Parameters| Name | In | Type | Required | Description |
|---|---|---|---|---|
org_slug |
path | string | yes | |
limit |
query | integer | no | Default: 20. |
offset |
query | integer | no | Default: 0. |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Charge a saved payment method and add credit to the customer's balance
Section titled Charge a saved payment method and add credit to the customer's balancePOST /api/v1/orgs/{org_slug}/portal/credit/topup/charge
Charge a saved payment method and add credit to the customer's balance.
amount is the credit to add, in US dollars, and the balance grows by exactly
that. We charge the payment method in currency at the exchange rate
GET .../storefront/currencies shows. Without currency we use the payment
method's own currency, then the customer's preferred pay currency. Answers 400
for a currency the customer cannot pay in, and 400 with This card cannot pay in <code>. Choose another card or pay with a new card. when currency is sent
and the payment account that holds the card does not take it (a Square card
takes US dollars only). We write nothing and charge nothing when we refuse.
The answer's status is succeeded when the credit was added, requires_action
while the customer must authenticate, and pending with a message while the
payment is on its way (a bank debit takes days). A pending payment adds the credit
by itself once it clears, so do not charge again. A declined charge answers 402.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
org_slug |
path | string | yes |
amount |
query | number or string | yes |
payment_method_id |
query | integer | yes |
currency |
query | string | no |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Hosted checkout to buy USD credit for an org customer
Section titled Hosted checkout to buy USD credit for an org customerPOST /api/v1/orgs/{org_slug}/portal/credit/topup/checkout
Hosted checkout to buy USD credit for an org customer.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
org_slug |
path | string | yes |
amount |
query | number or string | yes |
currency |
query | string | no |
gateway_name |
query | string | no |
return_url |
query | string | no |
cancel_url |
query | string | no |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Add credit for a card payment the customer finished in the page
Section titled Add credit for a card payment the customer finished in the pagePOST /api/v1/orgs/{org_slug}/portal/credit/topup/confirm-payment
Add credit for a card payment the customer finished in the page.
Send payment_intent_id, the gateway_reference that POST /orgs/{org_slug}/portal/credit/topup/pay-intent answered, and the
gateway_name it was made on. We read the payment from the card processor
and add the US dollars it was made for to the customer's balance, once:
sending it again answers succeeded and adds nothing. amount is optional.
When you send it, it must be within two cents of that amount, or we answer
400 amount does not match the completed payment. Answers requires_action
with a client_secret while the customer must still authenticate, pending
while the processor has not finished, and 402 when the payment did not
complete.
We add nothing and refuse a payment this customer did not make to add
credit. Answers 400 for a payment made for an invoice, 403 for a payment
another customer or another organization's customer made, 409 This payment has already been applied for a payment that already settled something else,
and 409 Your payment is being processed when the payment does not name its
top-up yet (the credit appears by itself once the processor confirms it).
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
org_slug |
path | string | yes |
gateway_name |
query | string | yes |
payment_intent_id |
query | string | yes |
amount |
query | number or string | no |
currency |
query | string | no |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Create a Stripe PaymentIntent to add credit in the page
Section titled Create a Stripe PaymentIntent to add credit in the pagePOST /api/v1/orgs/{org_slug}/portal/credit/topup/pay-intent
Create a Stripe PaymentIntent to add credit in the page.
Complete it with Stripe.js confirmPayment and the client_secret, then
call POST /orgs/{org_slug}/portal/credit/topup/confirm-payment, which
adds the credit. Without gateway_name we pick the Stripe account as
GET /orgs/{org_slug}/portal/credit/topup/pay-quote does.
Send expected_amount (the quote's charge_amount) from a wallet button.
When the amount has changed since the quote, for example because the
exchange rate moved, we answer 412 with detail.code amount_changed
and a new quote in detail.quote, and create nothing.
Parameters
Section titled Parameters| Name | In | Type | Required | Description |
|---|---|---|---|---|
org_slug |
path | string | yes | |
amount |
query | number or string | yes | US dollars of credit to add, from 5 to 10,000. |
currency |
query | string or null | no | Currency to charge in. Defaults to the customer's preferred pay currency. |
gateway_name |
query | string or null | no | Stripe account to charge through. Leave it out and we pick the account the pay intent picks. |
save_method |
query | boolean | no | Keep the payment method for later charges. A top-up does not keep it unless you ask. Default: False. |
expected_amount |
query | integer or null | no | The charge_amount from the top-up's pay quote, in minor units. When the amount has changed since, we answer 412 with a new quote and create nothing. |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
The card account and amount for adding credit in the page
Section titled The card account and amount for adding credit in the pageGET /api/v1/orgs/{org_slug}/portal/credit/topup/pay-quote
The card account and amount for adding credit in the page.
Ask for it before you draw the payment form. adapter says which form to
draw, and public holds that account's non-secret settings.
For adapter stripe, create Stripe's Express Checkout Element with
publishable_key, charge_amount, currency, save_method and
payment_method_configuration. Once the customer approves, create the
payment with POST /orgs/{org_slug}/portal/credit/topup/pay-intent with
the same amount, currency, gateway_name and save_method, and the
charge_amount as expected_amount.
For adapter square, draw Square's card form with
public.application_id and public.location_id, tokenize the card, and
send the token to POST /orgs/{org_slug}/portal/credit/topup/square-pay
with the same amount and the charge_amount as expected_amount. Square
takes US dollars only. When the account offers saved cards, ask for
save_method and send it to square-pay to keep the card.
renewal is always null for a top-up. Send card_adapters (for example
stripe,square) to say which card forms your frontend can draw. Without
it we pick among Stripe accounts only.
local_methods lists the payment methods made for the customer's country
that the quote's account can show in currency, as method tokens such as
ideal. It is empty when the customer has none, when the account shows
none, and until we have read the account's payment method settings, which a
quote never waits for. It is the same list the invoice quote gives.
A quote creates nothing and does not contact the card processor. Answers 400 for an amount outside 5 to 10,000 US dollars and for a currency that is not enabled or that the account does not take, and 503 when no account takes the currency.
Parameters
Section titled Parameters| Name | In | Type | Required | Description |
|---|---|---|---|---|
org_slug |
path | string | yes | |
amount |
query | number or string | yes | US dollars of credit to add, from 5 to 10,000. |
currency |
query | string or null | no | Currency to charge in. Defaults to the customer's preferred pay currency. |
gateway_name |
query | string or null | no | Card account to charge through. Leave it out and we pick the account your routing rules choose among the card_adapters you can draw. |
save_method |
query | boolean | no | Keep the payment method for later charges. A top-up does not keep it unless you ask. Default: False. |
card_adapters |
query | string or null | no | The card forms your frontend can draw, as a comma list of stripe and square. Defaults to stripe, so a frontend with no Square form keeps getting Stripe accounts. Send stripe,square once it can draw Square's card form: the quote then names whichever account your routing rules choose, and its adapter says which form to draw. |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Capture PayPal order and credit org customer balance
Section titled Capture PayPal order and credit org customer balancePOST /api/v1/orgs/{org_slug}/portal/credit/topup/paypal-capture
Capture PayPal order and credit org customer balance.
USD credit is derived from order custom_id=topup:<usd>; optional
amount may assert within $0.02.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
org_slug |
path | string | yes |
order_id |
query | string | yes |
gateway_name |
query | string | yes |
amount |
query | number or string | no |
currency |
query | string | no |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Add credit with a Square card token, in one request
Section titled Add credit with a Square card token, in one requestPOST /api/v1/orgs/{org_slug}/portal/credit/topup/square-pay
Add credit with a Square card token, in one request.
Draw Square's card form with the public settings of
GET /orgs/{org_slug}/portal/credit/topup/pay-quote?card_adapters=stripe,square
(when its adapter is square), tokenize the card in the browser, and
send the token as source_id with the same amount. We charge it in this
request and add the credit when Square takes the payment.
Send the quote's charge_amount as expected_amount. When the amount has
changed since, we answer 412 with detail.code amount_changed and a new
quote in detail.quote, and charge nothing. Send save_method true to keep
the card, honored only while the account offers saved cards. When a save was
asked for and the payment succeeds, the answer holds saved_method: true
when we saved the card, false with a plain message when we could not,
and the payment stays succeeded either way. Only a card can be saved. A
currency other than USD answers 400. source_kind and method work as
they do on the invoice route, and an ach top-up answers pending and
adds the credit when the bank confirms it, 2 to 3 business days later.
The answer has the shape of
POST /orgs/{org_slug}/portal/invoices/{invoice_id}/square-pay: status
is succeeded, pending or failed, and a declined card is HTTP 200 with
status failed and a plain message. A second request while the first
is still running answers 409 with a Retry-After header.
Parameters
Section titled Parameters| Name | In | Type | Required | Description |
|---|---|---|---|---|
org_slug |
path | string | yes | |
amount |
query | number or string or null | no | US dollars of credit to add, from 5 to 10,000. You can send it as amount_usd in the body instead. |
Request body
Section titled Request bodyapplication/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
gateway_name |
string or null | no | The Square account to charge through. Leave it out and we pick the account the pay quote picks. |
source_id |
string | yes | The payment token the Web Payments SDK returned from tokenize(). |
source_kind |
string, one of card, apple_pay, google_pay, ach, cash_app, afterpay or null |
no | The way of paying the token came from: card, apple_pay, google_pay, ach (a US bank account), cash_app or afterpay. Leave it out for a card. We refuse a way the account has not switched on, and a token that is not that kind of token, before we charge anything. Only a card can be saved: a save_method sent with any other kind is refused with saved_method false. An ach payment answers pending and settles 2 to 3 business days later. |
expected_amount |
integer or null | no | The quote's charge_amount in the smallest currency unit. When the amount due has moved since, we answer 412 and create nothing. |
save_method |
boolean | no | Keep the card for renewals. Honored only while the account offers saved cards (public.can_save_cards). |
verification_token |
string or null | no | The buyer verification token tokenize() returned, when it returned one. |
buyer_email |
string or null | no | Where Square sends its receipt, when you want one. |
billing |
SquareBilling or null | no | |
billing.given_name |
string or null | no | |
billing.family_name |
string or null | no | |
billing.email |
string or null | no | |
billing.phone |
string or null | no | |
billing.address_lines |
array of string or null | no | |
billing.city |
string or null | no | |
billing.state |
string or null | no | |
billing.postal_code |
string or null | no | |
billing.country_code |
string or null | no | |
currency |
string or null | no | The currency of the quote. Defaults to the account's pay currency. |
amount_usd |
number or string or null | no | US dollars to pay now, for part of an invoice. Defaults to everything still owed. |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |