Welcome to the heart of Portal Pay's functionality - the Payment system. Let's break down how payments work and how you can leverage them to create a seamless experience for your users.

Your Payment Toolkit: Available Endpoints

To interact with payments, you have three powerful endpoints at your disposal:

POST /payments: Create a new payment
GET /payments/{id}: Retrieve details of a specific payment
GET /payments: List all payments

These endpoints give you full control over the payment lifecycle.

Understanding the Payment Object

Think of a Payment object as a blueprint for a transaction. It's the foundation upon which actual transactions are built. Here's what you need to know:

It represents an intent to pay.
It works hand-in-hand with TransactionRequests to capture payments.
It specifies the base currency and amount, which are crucial for determining prices when a TransactionRequest is made.

👍
Pro Tip:
If you're using our Hosted Payment Page (and we hope you are!), you can set redirect URLs directly on the Payment object. This allows for a smooth, branded experience for your users throughout the payment process.

Tracking Payment Status

Every Payment object comes with a read-only status attribute. This is your window into the payment's journey through the Portal Pay system. Here's what each status means:

Status	Description
created	The payment has been initiated in our system
completed	Success! The full amount has been paid through a TransactionRequest.
refunded	The payment `amount` has been fully returned to the `sending_address` on the TransactionRequest
failed	Unfortunately, the payment attempt was unsuccessful.

By monitoring these statuses, you can keep your users informed and respond appropriately at each stage of the payment process.