Payments

A payment is a single attempt to move money into your Sphere account.

The payment object is an integral part of Sphere's system. payment objects are automatically created when a customer attempts to pay for a product through a payment method. It contains crucial information about the purchase, such as the associated customer, the transaction, the signature for the transaction, and involved line items, for you to consume on your backend and apply the appropriate business logic when a customer has bought one of your goods.

When interacting with Sphere's API, the payment object will be one of the most important pieces, as it keeps track of who has paid for which goods.

Endpoints

The Payment object

Properties

Name
id
Type
string
Description
Unique identifier for the object. Auto-generated by Sphere upon creation.
Name
type
Type
enum
Description
Identifies the payment method used for this payment. Either paymentLink or subscription.
Name
status
Type
enum
Description
Identifies the current status of the payment after the customer has submitted it.
- pending: The payment is still in the process of being submitted to the underlying network.
- confirmed: The payment has been confirmed by the underlying network.
- succeeded: The payment has been finalized by the underlying network.
- failed: The payment was rejected by the underlying network.
- refunded: The payment was returned back to the customer who submitted the transaction.
- Underlying network here means either a given blockchain or fiat rail (e.g., network).
Name
transaction
Type
string
Description
The id for the transaction object that contains key information of the payment flow.
Name
customer
Type
string
Description
The id of the associated customer used for the payment. Created upon instantiation of a payment if the customer does not already exist.
Name
lineItems
Type
object array
Description
A list of lineItems specifying what the customer purchased.
- Name
  quantity
  Type
  number
  Description
  The amount of a given product bought.
- Name
  quantityMutable
  Type
  boolean
  Description
  Determines if the customers can adjust the default quantity.
- Name
  quantityLabel
  Type
  string
  Description
  The label that describes what a quantity of a given product is. Useful for when you want to display a different label other than the Qty label on the checkout page (e.g., Months).
- Name
  price
  Type
  string
  Description
  The id of the price that will be used for the product during checkout.
- Name
  product
  Type
  number
  Description
  The id of the product that the line item points to; what the customer purchased.
- Name
  amountTotal
  Type
  number
  Description
  The total amount purchased, measured in the paymentCurrency.
- Name
  paymentCurrency
  Type
  string
  Description
  The public key for the mint address (Solana) or token contract address (EVM) used for the payment.
- Name
  updated
  Type
  string
  Description
  Datetime for when the line item was last updated.
- Name
  created
  Type
  string
  Description
  Datetime for when the line item was created.
Name
meta
Type
object
Description
Set of key-value pairs (JSON) for arbitrary usage. Used to save structured information about the object to reference elsewhere. Think of it as general purpose storage space.
Name
shipping
Type
object
Description
The shipping details for the payment. Empty if the paymentLink does not require the customer to provide their name or address.
- Name
  address
  Type
  object
  Description
  The address of the shipping details.
  
  Name
  line1
  Type
  string
  Description
  Address line 1 (e.g., street, PO Box, or company name).
  
  Name
  line2
  Type
  string
  Description
  Address line 2 (e.g., apartment, suite, unit, or building).
  
  Name
  city
  Type
  string
  Description
  City, district, suburb, town, or village.
  
  Name
  postalCode
  Type
  string
  Description
  ZIP or postal code.
  
  Name
  state
  Type
  string
  Description
  Two-letter state code (ISO3166 subdivision code)
  
  Name
  country
  Type
  string
  Description
  Three-letter country code (ISO 3166-1 alpha-3).
- Name
  firstName
  Type
  string
  Description
  The customer's first name.
- Name
  lastName
  Type
  string
  Description
  The customer's last name.
- Name
  phone
  Type
  string
  Description
  The customer's phone number.
Name
billing
Type
object
Description
The billing details for the payment. Empty if the paymentLink does not require the customer to provide their name, email, or address. Shares the same structure and values as shipping, asides from the email field.
- Name
  address
  Type
  object
  Description
  The address of the billing details.
  
  Name
  line1
  Type
  string
  Description
  Address line 1 (e.g., street, PO Box, or company name).
  
  Name
  line2
  Type
  string
  Description
  Address line 2 (e.g., apartment, suite, unit, or building).
  
  Name
  city
  Type
  string
  Description
  City, district, suburb, town, or village.
  
  Name
  postalCode
  Type
  string
  Description
  ZIP or postal code.
  
  Name
  state
  Type
  string
  Description
  Two-letter state code (ISO3166 subdivision code)
  
  Name
  country
  Type
  string
  Description
  Three-letter country code (ISO 3166-1 alpha-3).
- Name
  email
  Type
  string
  Description
  The customer's email address. Payment receipt emails will be sent to this address if provided.
- Name
  firstName
  Type
  string
  Description
  The customer's first name.
- Name
  lastName
  Type
  string
  Description
  The customer's last name.
- Name
  phone
  Type
  string
  Description
  The customer's phone number.
Name
txId
Type
string
Description
The transaction signature for the payment for the underlying network.
Name
taxRate
Type
string
Description
The id of the taxRate object used for the payment. Null by default.
Name
shippingRate
Type
string
Description
The id of the shippingRate object used for the payment. Null by default.
Name
paymentLink
Type
string
Description
The id of the payment link used for the payment.
Name
subscription
Type
string
Description
The subscription id associated with the payment. Null if the payment type is not subscription.
Name
updated
Type
string
Description
Datetime for when the payment was last updated.
Name
created
Type
string
Description
Datetime for when the payment was created.

Payment Object

  {
      "id": "payment_91521a1f00324b6e817897a59e6e7e3e",
      "type": "paymentLink",
      "status": "succeeded",
      "transaction": "transaction_f2eae0e84b9f4258a83c3652f0ee7543",
      "customer": "customer_4646908d5f5e45f0ab03d2cd80ab9031",
      "lineItems": [
        {
          "quantity": 1,
          "quantityMutable": true,
          "quantityLabel": "",
          "price": "price_be0e63a0a2b04e3da398d1b98f2d47d9",
          "product": "product_dfca88cf8f6f46a4ac7c940006d420af",
          "amountTotal": 1,
          "paymentCurrency": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
          "updated": "2024-05-07T20:12:51.049Z",
          "created": "2024-05-07T20:12:51.031Z"
        }
      ],
      "meta": {},
      "shipping": {
        "address": {
          "line1": null,
          "line2": null,
          "city": null,
          "postalCode": null,
          "state": null,
          "country": null
        },
        "firstName": "John",
        "lastName": "Doe",
        "phone": null
      },
      "billing": {
        "address": {
          "line1": null,
          "line2": null,
          "city": null,
          "postalCode": null,
          "state": null,
          "country": null
        },
        "email": "johndoe2331@spherepay.co",
        "firstName": "John",
        "lastName": "Doe",
        "phone": null
      },
      "txId": "5RASAsdJAFepDMNQqEmgdG3ZimcdRMaRzPRRssEykMyKAHzAk92oByUGoqAEZA3wQr7FYc9FsnUgBzYi7YBaBtUP",
      "taxRate": null,
      "shippingRate": null,
      "paymentLink": "paymentLink_fae6c06b207b403aadf2728a6f4dd70e",
      "subscription": null,
      "updated": "2024-05-07T20:13:03.327Z",
      "created": "2024-05-07T20:12:51.049Z"
    }

GET/v1/payment/:id

Retrieve a payment

Retrieves a payment object by id.

Request

GET

/v1/payment/:id

curl https://api.spherepay.co/v1/payment/payment_1e5e89e1319d42cda427df9d7ee0a1db \
  -H "Authorization: Bearer {token}"

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "payment": {
      "id": "payment_91521a1f00324b6e817897a59e6e7e3e",
      "type": "paymentLink",
      "status": "succeeded",
      "transaction": "transaction_f2eae0e84b9f4258a83c3652f0ee7543",
      "customer": "customer_4646908d5f5e45f0ab03d2cd80ab9031",
      "lineItems": [
        {
          "quantity": 1,
          "quantityMutable": true,
          "quantityLabel": "",
          "price": "price_be0e63a0a2b04e3da398d1b98f2d47d9",
          "product": "product_dfca88cf8f6f46a4ac7c940006d420af",
          "amountTotal": 1,
          "paymentCurrency": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
          "updated": "2024-05-07T20:12:51.049Z",
          "created": "2024-05-07T20:12:51.031Z"
        }
      ],
      "meta": {},
      "shipping": {
        "address": {
          "line1": null,
          "line2": null,
          "city": null,
          "postalCode": null,
          "state": null,
          "country": null
        },
        "firstName": "John",
        "lastName": "Doe",
        "phone": null
      },
      "billing": {
        "address": {
          "line1": null,
          "line2": null,
          "city": null,
          "postalCode": null,
          "state": null,
          "country": null
        },
        "email": "johndoe2331@gmail.com",
        "firstName": "John",
        "lastName": "Doe",
        "phone": null
      },
      "txId": "5RASAsdJAFepDMNQqEmgdG3ZimcdRMaRzPRRssEykMyKAHzAk92oByUGoqAEZA3wQr7FYc9FsnUgBzYi7YBaBtUP",
      "taxRate": null,
      "shippingRate": null,
      "paymentLink": "paymentLink_fae6c06b207b403aadf2728a6f4dd70e",
      "subscription": null,
      "updated": "2024-05-07T20:13:03.327Z",
      "created": "2024-05-07T20:12:51.049Z"
    }
  },
  "ts": "2024-08-08T20:31:24.814Z",
  "request": "request_59f6d7424e704b9ebba34a854ff5052c"
}

GET/v1/payment

List all payments

Returns a list of your payment objects, sorted by newest creation date first.

Parameters

Name
status
Type
string
Description
Filter by payment status. One of pending, confirming, succeeded, failed, or refunded.
Name
price
Type
string
Description
Filter by a price id.
Name
paymentLink
Type
string
Description
Filter by a paymentLink id.
Name
customer
Type
string
Description
Filter by a customer id.
Name
subscription
Type
string
Description
Filter by a subscription id.
Name
startDate
Type
string
Description
The start datetime that objects will begin to be pulled from.
Name
endDate
Type
string
Description
The end datetime that objects will be fetched until.
Name
limit
Type
integer
Description
The maximum number of objects to pull. Defaults to 25, maximum is 200.
Name
sort
Type
string
Description
Sort data by field.
Name
direction
Type
enum
Description
The direction that payments will be sorted in. Either ASC or DESC.

Request

GET

/v1/payment

curl -G https://api.spherepay.co/v1/payment \
  -H "Authorization: Bearer {token}" \
  -d limit=2

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "payments": [
      {
        "id": "payment_d845578afed64d66bee2450d3103fbf7",
        "type": "paymentLink",
        "status": "succeeded",
        "transaction": "transaction_3466d4c8212b4fe58da45df9585b1d54",
        "customer": "customer_4646908d5f5e45f0ab03d2cd80ab9031",
        "lineItems": [
          {
            "quantity": 3,
            "quantityMutable": true,
            "quantityLabel": "Donation Amount",
            "price": "price_d16b2638c0fa4d19a2c3d82d47594379",
            "product": "product_0b32235ed4904799ac821048db32ac6d",
            "amountTotal": 3,
            "paymentCurrency": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
            "updated": "2024-08-08T21:35:32.128Z",
            "created": "2024-08-08T21:35:32.118Z"
          }
        ],
        "meta": {},
        "shipping": {
          "address": {
            "line1": null,
            "line2": null,
            "city": null,
            "postalCode": null,
            "state": null,
            "country": null
          },
          "firstName": null,
          "lastName": null,
          "phone": null
        },
        "billing": {
          "address": {
            "line1": null,
            "line2": null,
            "city": null,
            "postalCode": null,
            "state": null,
            "country": null
          },
          "email": null,
          "firstName": null,
          "lastName": null,
          "phone": null
        },
        "txId": "346XiHaxpz1sBXir57DC6Pi3cchmH7xfqL84qtZvyxXmdBRdZ4cK2tAfNLdUFvmRbZZ2RVULNpnMfY3KHP6kQ99u",
        "taxRate": null,
        "shippingRate": null,
        "paymentLink": "paymentLink_ce24539cf6ad40a0b329712734718e08",
        "subscription": null,
        "updated": "2024-08-08T21:35:41.732Z",
        "created": "2024-08-08T21:35:32.128Z"
      },
      {
        "id": "payment_844fd2498b4142749dfbfd96dbb1a5f7"
        // ...
      }
    ]
  },
  "ts": "2024-08-08T21:43:53.283Z",
  "request": "request_a1672207abb845dd8b6b195524e84ae9"
}