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.

The Payment object

Properties

  • Name
    id
    Type
    string
    Description

    A unique identifier for the object.

  • 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"
}

Was this page helpful?