Backend API
When a store accepts payment of any kind, a record is kept along with its relation to an order or invoice. Related orders and invoices are automatically updated with payment totals. When a refund is issued, the amount_refunded is also updated.
Fields
id
objectIdUnique identifier for the payment.
account
AccountExpandable link to the customer's account that made the payment.
account_card
Account CardExpandable link to the customer's credit card on file used to make the payment, if applicable.
account_card_id
objectIdID of the customer's credit card on file used to make the payment, if applicable.
account_id
objectIdrequiredID of the customer's account the payment was made for.
amazon
objectAmazon billing details used when method=amazon.
amazon.access_token
stringAmazon access token provided when a customer authorizes payment in a storefront.
amazon.order_reference_id
stringAmazon order reference ID created when a customer initiates payment in a storefront.
amazon.checkout_session_id
stringamount
currencyrequiredPayment amount denominated in currency. Minimum of 0.01
amount_refundable
currencyautoRemaining amount that can be refunded.
amount_refunded
currencyautoAmount of the payment that has been refunded.
async
booleanautoIndicates the payment is processed asynchronously. The payment will be updated in the future while success is undefined.
authorized
booleanIndicates the payment was authorized before being captured.
captured
booleanIndicates the payment has been captured.
card
objectCredit card details used to make the payment, if applicable.
card.token
stringrequiredA temp token generated by Swell Checkout or Stripe.js, or a permanent card token assigned after submitting a temporary token (starting with card_).
card.exp_month
intTwo-digit number representing the credit card expiration month.
card.exp_year
intFour-digit number representing the credit card expiration year.
card.brand
stringCredit card brand. Can be American Express, Diners Club, Discover, JCB, MasterCard, UnionPay, Visa, or Unknown.
card.last4
stringLast four digits of the card number.
card.test
booleanIndicates this is a test card.
card.address_check
stringWhen used with a payment gateway that performs address checks and address1 was provided, can be pass, fail, unavailable, or unchecked.
card.zip_check
stringWhen used with a payment gateway that performs address checks and zip was provided, can be pass, fail, unavailable, or unchecked.
card.cvc_check
stringWhen used with a payment gateway that performs CVC code checks and cvc was provided, can be pass, fail, unavailable, or unchecked.
currency
stringThree-letter ISO currency code in uppercase. Defaults to the store's base currency.
currency_rate
floatCurrency percentage used in calculating the fixed amount.
date_async_update
dateThe date of the next time the payment status will be updated.
date_created
dateautoDate and time the payment was created.
date_updated
dateautoDate and time the payment was last updated.
error
objectAn object describing an error that occurred while interacting with the payment gateway, if applicable.
error.code
stringUnique error code.
error.message
stringA message describing the error.
gateway
stringautoID of the payment gateway that was used to process the payment.
giftcard
Gift CardExpandable link to gift card used to make the payment, if applicable.
giftcard_id
objectIdID of the gift card used to make the payment, if applicable.
intent
objectThe intent of the external payment provider. See the external payment provider’s documentation for how intent is implemented.
invoice
InvoiceExpandable link to the invoice the payment was applied to, if applicable.
invoice_id
objectIdID of the invoice the payment was applied to, if applicable.
method
stringrequiredMethod of payment. Can be card, account, amazon, paypal or any one of the manual methods defined in payment settings.
number
stringautoUnique incremental payment number assigned automatically.
order
OrderExpandable link to the order the payment was applied to, if applicable.
order_id
objectIdID of the order the payment was applied to, if applicable.
paypal
objectPayPal billing details used when billing.method=paypal.
paypal.payer_id
stringPayPal payer ID provided when a customer authorizes payment in a storefront.
paypal.payment_id
stringPayPal payment ID created when a customer initiates payment in a storefront.
refunds
array of RefundsExpandable list of refunds issued for the payment.
status
enumautoStatus of the payment. Can be pending, which is awaiting async processing, error, success or authorized.
Possible enum values:
subscription
SubscriptionExpandable link to the subscription the payment was applied to, if applicable.
subscription_id
objectIdautoID of the subscription the payment was applied to, if applicable.
success
booleanIndicates the payment was successful. When an error occurs with a payment gateway, this status will be false and error field will be populated.
test
booleanautoIndicates the payment was made with a gateway in test mode.
transaction_id
stringautoExternal identifier returned by a payment gateway, if applicable.
The payment model
{
"id": "60f199509111e70000000056",
"account_id": "60f199509111e7000000005a",
"amount": 50,
"method": "card",
"account_card_id": "60f199509111e70000000058",
"amount_refundable": 30,
"amount_refunded": 20,
"async": false,
"authorized": true,
"captured": true,
"card": {
"token": "card_1Ds1K7E30PFlZWil6Q7bJ1PD",
"test": true,
"last4": "4242",
"brand": "Visa",
"address_check": "unchecked",
"zip_check": "unchecked",
"cvc_check": "unchecked",
"exp_month": 1,
"exp_year": 2029
},
"currency": "USD",
"date_created": "2021-07-16T14:36:00.313Z",
"date_updated": "2021-07-16T14:36:00.313Z",
"error": null,
"gateway": "stripe",
"number": 2973512,
"order_id": "60f199509111e70000000059",
"status": "success",
"success": true,
"test": true,
"transaction_id": "ch_1XNoXdEAeofUkt5SrbA6Swow"
}
Create a new payment. If you wish to generate your own unique ID for the record, it must use BSON ObjectID format for compatibility.
Arguments
account_id
objectIdrequiredID of the customer's account the payment was made for.
amount
currencyrequiredPayment amount denominated in currency. Minimum of 0.01
method
stringrequiredMethod of payment. Can be card, account, amazon, paypal or any one of the manual methods defined in payment settings.
card
objectCredit card details used to make the payment, if applicable.
card.token
stringrequiredA temp token generated by Swell Checkout or Stripe.js, or a permanent card token assigned after submitting a temporary token (starting with card_).
card.exp_month
intTwo-digit number representing the credit card expiration month.
card.exp_year
intFour-digit number representing the credit card expiration year.
card.brand
stringCredit card brand. Can be American Express, Diners Club, Discover, JCB, MasterCard, UnionPay, Visa, or Unknown.
card.last4
stringLast four digits of the card number.
card.test
booleanIndicates this is a test card.
card.address_check
stringWhen used with a payment gateway that performs address checks and address1 was provided, can be pass, fail, unavailable, or unchecked.
card.zip_check
stringWhen used with a payment gateway that performs address checks and zip was provided, can be pass, fail, unavailable, or unchecked.
card.cvc_check
stringWhen used with a payment gateway that performs CVC code checks and cvc was provided, can be pass, fail, unavailable, or unchecked.
invoice_id
objectIdID of the invoice the payment was applied to, if applicable.
order_id
objectIdID of the order the payment was applied to, if applicable.
account
AccountExpandable link to the customer's account that made the payment.
account_card
Account CardExpandable link to the customer's credit card on file used to make the payment, if applicable.
account_card_id
objectIdID of the customer's credit card on file used to make the payment, if applicable.
amazon
objectAmazon billing details used when method=amazon.
amazon.access_token
stringAmazon access token provided when a customer authorizes payment in a storefront.
amazon.order_reference_id
stringAmazon order reference ID created when a customer initiates payment in a storefront.
amazon.checkout_session_id
stringamount_refundable
currencyautoRemaining amount that can be refunded.
amount_refunded
currencyautoAmount of the payment that has been refunded.
async
booleanautoIndicates the payment is processed asynchronously. The payment will be updated in the future while success is undefined.
authorized
booleanIndicates the payment was authorized before being captured.
captured
booleanIndicates the payment has been captured.
currency
stringThree-letter ISO currency code in uppercase. Defaults to the store's base currency.
currency_rate
floatCurrency percentage used in calculating the fixed amount.
date_async_update
dateThe date of the next time the payment status will be updated.
error
objectAn object describing an error that occurred while interacting with the payment gateway, if applicable.
error.code
stringUnique error code.
error.message
stringA message describing the error.
gateway
stringautoID of the payment gateway that was used to process the payment.
giftcard
Gift CardExpandable link to gift card used to make the payment, if applicable.
giftcard_id
objectIdID of the gift card used to make the payment, if applicable.
intent
objectThe intent of the external payment provider. See the external payment provider’s documentation for how intent is implemented.
invoice
InvoiceExpandable link to the invoice the payment was applied to, if applicable.
number
stringautoUnique incremental payment number assigned automatically.
order
OrderExpandable link to the order the payment was applied to, if applicable.
paypal
objectPayPal billing details used when billing.method=paypal.
paypal.payer_id
stringPayPal payer ID provided when a customer authorizes payment in a storefront.
paypal.payment_id
stringPayPal payment ID created when a customer initiates payment in a storefront.
refunds
array of RefundsExpandable list of refunds issued for the payment.
status
enumautoStatus of the payment. Can be pending, which is awaiting async processing, error, success or authorized.
Possible enum values:
subscription
SubscriptionExpandable link to the subscription the payment was applied to, if applicable.
subscription_id
objectIdautoID of the subscription the payment was applied to, if applicable.
success
booleanIndicates the payment was successful. When an error occurs with a payment gateway, this status will be false and error field will be populated.
test
booleanautoIndicates the payment was made with a gateway in test mode.
transaction_id
stringautoExternal identifier returned by a payment gateway, if applicable.
const swell = require('swell-node').init('store-id', 'secret-key');
await swell.post('/payments', {
amount: 50,
method: 'card',
card: { token: 'card_XfqLq5nRdOdu7vTvoeKufafN' },
account_id: '5c899d4f7d7920749638dc4e',
});
Response
{
"id": "5cae685b20a54174dd968afa",
"account_id": "5c899d4f7d7920749638dc4e",
"amount": 50,
"amount_refundable": 50,
"authorized": true,
"captured": true,
"card": {
"brand": "Visa",
"last4": "4242",
"exp_month": 10,
"exp_year": 2029,
"token": "card_XfqLq5nRdOdu7vTvoeKufafN",
"cvc_check": "pass",
"zip_check": "pass",
"address_check": "pass"
},
"currency": "USD",
"date_created": "2019-04-01T00:00:00.000Z",
"date_updated": "2019-04-01T00:00:00.000Z",
"gateway": "stripe",
"method": "card",
"number": "1947367",
"order_id": "5cae685b20a54174dd968077",
"status": "success",
"success": true,
"transaction_id": "ch_1XNoXdEAeofUkt5SrbA6Swow"
}
Retrieve an existing payment using the ID that was returned when created.
Arguments
id
objectIdrequiredThe id of the payment to retrieve.
expand
stringExpanding link fields and child collections is performed using the expand argument.
- For example, expand=account would return a related customer account if one exists.
When the field represents a collection, you can specify the query limit.
- For example, expand=variants:10 would return up to 10 records of the variants collection.
See expanding for more details.
fields
stringReturn only the specified fields in the result. For example fields=name,slug would return only the fields name and slug in the response. Supports nested object and array fields using dot-notation.
- For example, items.product_id. The category id is always returned.
include
stringInclude one or more arbitrary queries in the response, possibly related to the main query.
See including for more details.
const swell = require('swell-node').init('store-id', 'secret-key');
await swell.get('/payments/{id}', {
id: '5cae685b20a54174dd968afa',
});
Response
{
"id": "5cae685b20a54174dd968afa",
"account_id": "5c899d4f7d7920749638dc4e",
"amount": 50,
"amount_refundable": 50,
"authorized": true,
"captured": true,
"card": {
"brand": "Visa",
"last4": "4242",
"exp_month": 10,
"exp_year": 2029,
"token": "card_XfqLq5nRdOdu7vTvoeKufafN",
"cvc_check": "pass",
"zip_check": "pass",
"address_check": "pass"
},
"currency": "USD",
"date_created": "2019-04-01T00:00:00.000Z",
"date_updated": "2019-04-01T00:00:00.000Z",
"gateway": "stripe",
"method": "card",
"number": "1947367",
"order_id": "5cae685b20a54174dd968077",
"status": "success",
"success": true,
"transaction_id": "ch_1XNoXdEAeofUkt5SrbA6Swow"
}
Updating a payment with the Swell Backend API.
Arguments
id
objectIdrequiredUnique identifier for the payment.
captured
booleanIndicates the payment has been captured.
transaction_id
stringautoExternal identifier returned by a payment gateway, if applicable.
account_id
objectIdrequiredID of the customer's account the payment was made for.
amount
currencyrequiredPayment amount denominated in currency. Minimum of 0.01
method
stringrequiredMethod of payment. Can be card, account, amazon, paypal or any one of the manual methods defined in payment settings.
account
AccountExpandable link to the customer's account that made the payment.
account_card
Account CardExpandable link to the customer's credit card on file used to make the payment, if applicable.
account_card_id
objectIdID of the customer's credit card on file used to make the payment, if applicable.
amazon
objectAmazon billing details used when method=amazon.
amazon.access_token
stringAmazon access token provided when a customer authorizes payment in a storefront.
amazon.order_reference_id
stringAmazon order reference ID created when a customer initiates payment in a storefront.
amazon.checkout_session_id
stringamount_refundable
currencyautoRemaining amount that can be refunded.
amount_refunded
currencyautoAmount of the payment that has been refunded.
async
booleanautoIndicates the payment is processed asynchronously. The payment will be updated in the future while success is undefined.
authorized
booleanIndicates the payment was authorized before being captured.
card
objectCredit card details used to make the payment, if applicable.
card.token
stringA temp token generated by Swell Checkout or Stripe.js, or a permanent card token assigned after submitting a temporary token (starting with card_).
card.exp_month
intTwo-digit number representing the credit card expiration month.
card.exp_year
intFour-digit number representing the credit card expiration year.
card.brand
stringCredit card brand. Can be American Express, Diners Club, Discover, JCB, MasterCard, UnionPay, Visa, or Unknown.
card.last4
stringLast four digits of the card number.
card.test
booleanIndicates this is a test card.
card.address_check
stringWhen used with a payment gateway that performs address checks and address1 was provided, can be pass, fail, unavailable, or unchecked.
card.zip_check
stringWhen used with a payment gateway that performs address checks and zip was provided, can be pass, fail, unavailable, or unchecked.
card.cvc_check
stringWhen used with a payment gateway that performs CVC code checks and cvc was provided, can be pass, fail, unavailable, or unchecked.
currency
stringThree-letter ISO currency code in uppercase. Defaults to the store's base currency.
currency_rate
floatCurrency percentage used in calculating the fixed amount.
date_async_update
dateThe date of the next time the payment status will be updated.
error
objectAn object describing an error that occurred while interacting with the payment gateway, if applicable.
error.code
stringUnique error code.
error.message
stringA message describing the error.
gateway
stringautoID of the payment gateway that was used to process the payment.
giftcard
Gift CardExpandable link to gift card used to make the payment, if applicable.
giftcard_id
objectIdID of the gift card used to make the payment, if applicable.
intent
objectThe intent of the external payment provider. See the external payment provider’s documentation for how intent is implemented.
invoice
InvoiceExpandable link to the invoice the payment was applied to, if applicable.
invoice_id
objectIdID of the invoice the payment was applied to, if applicable.
number
stringautoUnique incremental payment number assigned automatically.
order
OrderExpandable link to the order the payment was applied to, if applicable.
order_id
objectIdID of the order the payment was applied to, if applicable.
paypal
objectPayPal billing details used when billing.method=paypal.
paypal.payer_id
stringPayPal payer ID provided when a customer authorizes payment in a storefront.
paypal.payment_id
stringPayPal payment ID created when a customer initiates payment in a storefront.
refunds
array of RefundsExpandable list of refunds issued for the payment.
status
enumautoStatus of the payment. Can be pending, which is awaiting async processing, error, success or authorized.
Possible enum values:
subscription
SubscriptionExpandable link to the subscription the payment was applied to, if applicable.
subscription_id
objectIdautoID of the subscription the payment was applied to, if applicable.
success
booleanIndicates the payment was successful. When an error occurs with a payment gateway, this status will be false and error field will be populated.
test
booleanautoIndicates the payment was made with a gateway in test mode.
const swell = require('swell-node').init('store-id', 'secret-key');
await swell.post('/payments/{id}', {
captured: true,
transaction_id: ch_1XNoXdEAeofUkt5SrbA6Swow,
});
Arguments
amount
currencyrequiredAmount to refund up to payment amount_refundable.
method
stringOptionally refund the payment using a different method. Defaults to the original payment method.
reason
booleanThe reason of the refund.
reason_message
stringA brief message describing the reason for the refund.
const swell = require('swell-node').init('store-id', 'secret-key');
await swell.post('/payments/{id}/refunds', {
id: '5cae685b20a54174dd968afa',
amount: 50,
});
Response
{
"id": "5cae042722984c53002096ab",
"amount": 50,
"card": {
"brand": "Visa",
"last4": "4242",
"exp_month": 10,
"exp_year": 2029,
"token": "card_XfqLq5nRdOdu7vTvoeKufafN",
"cvc_check": "pass",
"zip_check": "pass",
"address_check": "pass"
},
"currency": "USD",
"date_created": "2019-04-01T00:00:00.000Z",
"gateway": "stripe",
"method": "card",
"number": "103352",
"order_id": "5cae685b20a54174dd968077",
"parent_id": "5cae685b20a54174dd968afa",
"status": "success",
"success": true,
"transaction_id": "re_1XNhqtFAeoMUkt5CitcnPNAa"
}
Return a list of payments.
Arguments
expand
stringExpand link fields and child collections by using the expand argument.
- For example, expand=account would return a related customer account if one exists.
When the field represents a collection, you can specify the query limit.
- For example, expand=variants:10 would return up to 10 records of the variants collection.
See expanding for more details.
fields
stringReturns only the specified fields in the result.
- For example fields=name,slug would return only the fields name and slug in the response.
Supports nested object and array fields using dot-notation.
- For example, items.product_id. The product id is always returned.
include
objectInclude one or more arbitrary queries in the response which are potentially related to the main query.
See including for more details.
limit
intLimit the number of records returned, ranging between 1 and 1000. Defaults to 15.
page
intThe page number of results to return given the specified or default limit.
search
stringA text search is performed using the search argument. Searchable fields are defined by the model.
- For example, search=red would return records containing the word "red" anywhere in the defined text fields.
See searching for more details.
sort
stringExpression to sort results by using a format similar to a SQL sort statement.
- For example, sort=name asc would return records sorted by name ascending.
See sorting for more details.
where
objectAn object with criteria to filter the result.
- For example, active=true would return records containing a field active with the value true.
It's also possible to use query operators, for example, $eq, $ne, $gt, and more.
See querying for more details.
const swell = require('swell-node').init('store-id', 'secret-key');
await swell.get('/payments', {
limit: 25,
page: 1
});
Response
{
"count": 51,
"results": [
{
"id": "60f199509111e70000000056",
"account_id": "60f199509111e7000000005e",
"amount": 50,
"method": "card",
"account_card_id": "60f199509111e70000000058",
"amount_refundable": 30,
"amount_refunded": 20,
"async": false,
"authorized": true,
"captured": true,
"card": {
"token": "card_1Ds1K7E30PFlZWil6Q7bJ1PD",
"test": true,
"last4": "4242",
"brand": "Visa",
"address_check": "unchecked",
"zip_check": "unchecked",
"cvc_check": "unchecked",
"exp_month": 1,
"exp_year": 2029
},
"currency": "USD",
"date_created": "2021-07-16T14:36:00.313Z",
"date_updated": "2021-07-16T14:36:00.313Z",
"error": null,
"gateway": "stripe",
"number": 2973512,
"order_id": "60f199509111e70000000059",
"status": "success",
"success": true,
"test": true,
"transaction_id": "ch_1XNoXdEAeofUkt5SrbA6Swow"
},
{...},
{...}
],
"page": 1,
"pages": {
"1": {
"start": 1,
"end": 25
},
"2": {
"start": 26,
"end": 50
},
"2": {
"start": 51,
"end": 51
}
}
}