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. Consequently, it contains a lot of information.

The payment object

Let's take a look at a full payment object:

{
  "id": "payment_58cd82c526d04b21b5102bfc0925d898",
  "type": "paymentLink",
  "status": "succeeded",
  "transactions": [
    {
      "id": "transaction_1c7986f2575146359aca0b9bf0710dd6",
      "type": "payment",
      "rails": "fiat",
      "network": "sol",
      "flow": "debit",
      "amount": "5000000",
      "updated": "2021-01-01T00:00:00.000Z",
      "created": "2021-01-01T00:00:00.000Z"
    }
  ],
  "paymentLink": {
    "id": "paymentLink_bf1eb33193854b07b41e8c5df2733a7b",
    "name": "Example Payment Link",
    "description": "An example Payment Link for receiving payments.",
    "meta": "instant",
    "url": "https://spherepay.co/pay/paymentLink/paymentLink_c9dd7b0074d74be6bce2fedc8bf3b55f",
    "successUrl": "https://spherepay.co",
    "failUrl": "https://spherepay.co",
    "start": "2021-01-01T00:00:00.000Z",
    "end": "2021-01-01T00:00:00.000Z",
    "lineItems": [
      {
        "price": "lineItem_e91c38b5cf2b4bdd8ca8b3ef8c92b6b9",
        "quantity": 3
      },
      {
        "price": "lineItem_6d7d03eaecf34903922b5e464e39c2ee",
        "quantity": 5
      }
    ],
    "features": {
      "requiresEmail": true,
      "requiresName": true,
      "requiresShippingDetails": true
    },
    "updated": "2021-01-01T00:00:00.000Z",
    "created": "2021-01-01T00:00:00.000Z"
  },
  "customer": {
    "id": "customer_d779952e7aef4743afad8265e5ae26cb",
    "solanaPubKey": "8JFTv1FHAqEgupBxHmkzDwtRGtPojCQ4KyxE3HXGVN2i",
    "delinquent": false,
    "amountUSD": 42,
    "personalInfo": {
      "id": "personalInfo_8d44dfbb0e7249f9a886cd4935d04dc3",
      "email": "[email protected]",
      "firstName": "John",
      "lastName": "Smith",
      "phoneNumber": "+242-152-1512",
      "address": {
        "id": "address_d94987b5fc8642d8b1dd6e2ffcdc0d5b",
        "line1": "1 Hacker Way",
        "line2": "Building 32 Suite D",
        "city": "Menlo Park",
        "postalCode": "94025",
        "state": "San Francisco",
        "country": "US",
        "updated": "2021-01-01T00:00:00.000Z",
        "created": "2021-01-01T00:00:00.000Z"
      },
      "discord": "JohnSmith#1234",
      "twitter": "@JohnSmith",
      "telegram": "@JohnSmith"
    },
    "updated": "2021-01-01T00:00:00.000Z",
    "created": "2021-01-01T00:00:00.000Z"
  },
  "transport": {
    "solana": {
      "id": "solanaTransport_a25501cb183b47f3af4fb965df8f1817",
      "tx": "A1cu36RiU6kBvQLozv4CvOuDxr06kxZPaCS4WDmJZuCVSu/2sJrxzuRRdzYHFJM/vu/8794Hk14MJCUrLCESuwgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAIADAAMIrCjSwzcmokRYmi4Pnh+BpaEPRNXHbm6XroIO5BQwI27Z99UgA2OCG0K8V2X8J6seRpJjjiDYu4HNDfzNeynCvyAJ71Ftrox7KoILM4yicube+EtlVQ5uxjGpv/6KY1UfAcj9bZyMLgZh+jk790qmQJ7CsTvks74Rd9hr/nPBwuNV0qBH63GLaW1/P3r5GSx/pd4F579b9H6oo5M/mHAI9AMGRm/lIRcy/+ytunLDm+e8jOW7xfcSayxDmzpAAAAAOI9idf3s5X8gY3HjwlqbxUiZ5cM/dze17aIY+/DCpAwGp9UXGSxcUSGMyUw9SvF/WNruCJuh/UTj29mKAAAAAFUuU0w53X/KJHZR4AfWWf3toCBaExfX2IeU48S3KGKSAgUABQLAXBUABhAIAQECAgkKAwQLBAsEDAcNPHFhpQibvdDoIAAAAGhhc2hfMDVmM2FlODhjZWUxNDBkN2I4ZmYzZTZmMTEycDAAAAAAAADGhgEAAAAAAAED84lUVVPga8IpchNrNiIwclxV/+xpGiuS7d+jn4m8cQELBRIUBRMH",
      "swapTx": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAQAGDCAJ71Ftrox7KoILM4yicube+EtlVQ5uxjGpv/6KY1Ufp1H8ybFeAyfHf5ps4RBq55zapkVTaVtbBGBmDucHPWlV0qBH63GLaW1/P3r5GSx/pd4F579b9H6oo5M/mHAI9HIeQ8QICVdlUaO8oeu579iVNrlDfSs9mLIIInOkJ6oVIYgU/ZCjgQvvqAJSeG8Y2lfVN0WNxWBU0p7PiPXIFzFKV7JHNBX7ls426r36PakQMZr4FqoCsKEkM2nIZuHNLQMGRm/lIRcy/+ytunLDm+e8jOW7xfcSayxDmzpAAAAAjJclj04kifG7PRApFI4NgwtaE5na/xCEBI572Nvp+FkGm4hX/quBhPtof2NGGMA12sQ53BrrO1WYoPAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABt324ddloZPZy+FGzut5rBy0he1fWzeROoz1hX7/AKkEedUt7b9rxezQnYRTSjSupZdQQ7Nv0CskZQu1hENZXPKVHg3b6DOJ8EXb1hjTCH6M1nqSYFanQWBuDR8BKYHtBgYABQLAXBUABwYAAQAICQoACQIAAQwCAAAAZFoIAAAAAAAKAQEBEQsNDwoADAENAg4DBAQQBRwnOiaAZD6/+XAwAAAAAAAAwU8IAAAAAAAyAAEACgMBAAABCQHO40x21uQ4emb3ZN7H4IuIwAZqpTvki2wqSK5b3K5jigPMzc4CPNI=",
      "hash": "hash_88c69c76e8784e639398b44adba",
      "solanaEvent": {
        "id": "solanaEvent_8124ecfa234c44ec996834c9645a3090",
        "name": "transfer",
        "txSig": "5we4Lry8hVvFL1zW6bxSAxLg9k83MUq4iTq3Seb5jxkNrUMFz3w4kRTVouchE61m95ybuygapweVD7JDDrYuYGKV",
        "slot": 192457289,
        "blockTime": 1683389477,
        "errored": false,
        "updated": "2021-01-01T00:00:00.000Z",
        "created": "2021-01-01T00:00:00.000Z"
      },
      "updated": "2021-01-01T00:00:00.000Z",
      "created": "2021-01-01T00:00:00.000Z"
    }
  },
  "updated": "2021-01-01T00:00:00.000Z",
  "created": "2021-01-01T00:00:00.000Z"
}

id: string Unique identifier for the object. Auto-generated by Sphere upon creation.

type: enum Identifies the payment method used for this payment.

One of paymentLink, invoice, and subscription.

status: enum 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).

transactions: object Contains key information about the payment transaction.

id: string Unique identifier for the transaction. auto-generated by Sphere upon creation.
type: enum One of payment or refund depending on the direction of payment.
rails: enum Identifies whether the payment is crypto or fiat.
network: enum Identifies the blockchain or fiat method (e.g., card, wire, ACH).
flow: enum Identifies whether the payment is debit (incoming) or credit (outgoing).
amount: number Defines the positive integer amount for the payment.
updated: string datetime for when the transaction was last updated.
created: string datetime for when the transaction was created.

paymentLink: string the id for the associated payment link used as the payment method.

Set to null if the payment method was an invoice or another payment method.

customer: string the id for the associated customer for the payment.

Is created upon instantiation of a payment if the customer does not already exist.

transport: object The transaction metadata, including the transaction, signature, and swap information.

Identifies the underlying network of the transaction, such as solana or ethereum.
For Solana transactions, includes information that is standard to a transaction, such as the transaction signature (txSig), the program transaction (pTx), any fees, log messages, pre-and-post token balances, instructions, accounts, as well as the slot and block time of the transaction, and any token swaps if relevant.

updated: string datetime for when the payment was last updated.

created: string datetime for when the payment was created.