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. 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
, andsubscription
.
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 ofpayment
orrefund
depending on the direction of payment.rails
:enum
Identifies whether the payment iscrypto
orfiat
.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 aninvoice
or another payment method.
customer
: string
the id
for the associated customer for the payment.
- Is created upon instantiation of a
payment
if thecustomer
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
orethereum
. - 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.