APIExtensionsDeveloperUserReleasesDemoSupport
  • V 1

    • Summary
    • Address
    • Checkouts
    • Countries
    • Customer Returns
    • Line Items
    • Option Types
    • Option Values
    • Orders
    • Payments
    • Product Images
    • Product Properties
    • Products
    • Return Authorizations
    • Shipments
    • States
    • Stock Items
    • Stock Locations
    • Stock Movements
    • Taxonomies
    • Users
    • Variants
    • Zones

Table Of Contents

IndexParametersResponseSearchResponseSorting resultsNewResponseCreateResponseShowResponseAuthorizeResponseFailed ResponseCaptureResponseFailed ResponsePurchaseResponseFailed ResponseVoidResponseFailed ResponseCreditResponseFailed ResponseCredit Over Limit Response

Payments

Index

To see details about an order’s payments, make this request:

GET /api/v1/orders/R1234567/payments

Payments are paginated and can be iterated through by passing along a page parameter:

GET /api/v1/orders/R1234567/payments?page=2

Parameters

page:

The page number of payments to display.

per_page:

The number of payments to return per page

Response

Status:
200 OK
{
"payments": [
{
"id": 1,
"source_type": "Spree::CreditCard",
"source_id": 1,
"amount": "10.00",
"display_amount": "$10.00",
"payment_method_id": 1,
"state": "checkout",
"avs_response": null,
"created_at": "2012-10-24T23:26:23Z",
"updated_at": "2012-10-24T23:26:23Z",
"number": "P58PJCXG"
}
],
"count": 2,
"current_page": 1,
"pages": 2
}

Search

To search for a particular payment, make a request like this:

GET /api/v1/orders/R1234567/payments?q[response_code_cont]=123

The searching API is provided through the Ransack gem which Spree depends on. The response_code_cont here is called a predicate, and you can learn more about them by reading about Predicates on the Ransack wiki.

The search results are paginated.

Response

Status:
200 OK
{
"payments": [
{
"id": 1,
"source_type": "Spree::CreditCard",
"source_id": 1,
"amount": "10.00",
"display_amount": "$10.00",
"payment_method_id": 1,
"state": "checkout",
"avs_response": null,
"created_at": "2012-10-24T23:26:23Z",
"updated_at": "2012-10-24T23:26:23Z",
"number": "P58PJCXG"
}
],
"count": 2,
"current_page": 1,
"pages": 2
}

Sorting results

Results can be returned in a specific order by specifying which field to sort by when making a request.

GET /api/v1/payments?q[s]=state%20desc

New

In order to create a new payment, you will need to know about the available payment methods and attributes. To find these out, make this request:

GET /api/v1/orders/R1234567/payments/new

Response

Status:
200 OK
{
  "attributes": ["id", "source_type", "source_id", "amount",
   "display_amount", "payment_method_id", "state", "avs_response",
   "created_at", "updated_at", "number"],
  "payment_methods": [Spree::Resources::PAYMENT_METHOD]
}

Create

To create a new payment, make a request like this:

POST /api/v1/orders/R1234567/payments?payment[payment_method_id]=1&payment[amount]=10

Response

Status:
201 Created
{
"id": 1,
"source_type": "Spree::CreditCard",
"source_id": 1,
"amount": "10.00",
"display_amount": "$10.00",
"payment_method_id": 1,
"state": "checkout",
"avs_response": null,
"created_at": "2012-10-24T23:26:23Z",
"updated_at": "2012-10-24T23:26:23Z",
"number": "P58PJCXG"
}

Show

To get information for a particular payment, make a request like this:

GET /api/v1/orders/R1234567/payments/1

Response

Status:
200 OK
{
"id": 1,
"source_type": "Spree::CreditCard",
"source_id": 1,
"amount": "10.00",
"display_amount": "$10.00",
"payment_method_id": 1,
"state": "checkout",
"avs_response": null,
"created_at": "2012-10-24T23:26:23Z",
"updated_at": "2012-10-24T23:26:23Z",
"number": "P58PJCXG"
}

Authorize

To authorize a payment, make a request like this:

PUT /api/v1/orders/R1234567/payments/1/authorize

Response

Status:
200 OK
{
"id": 1,
"source_type": "Spree::CreditCard",
"source_id": 1,
"amount": "10.00",
"display_amount": "$10.00",
"payment_method_id": 1,
"state": "checkout",
"avs_response": null,
"created_at": "2012-10-24T23:26:23Z",
"updated_at": "2012-10-24T23:26:23Z",
"number": "P58PJCXG"
}

Failed Response

Status:
422 Unprocessable Entity
{
  "error": "There was a problem with the payment gateway: [text]"
}

Capture

Capturing a payment is typically done shortly after authorizing the payment. If you are auto-capturing payments, you may be able to use the purchase endpoint instead.

To capture a payment, make a request like this:

PUT /api/v1/orders/R1234567/payments/1/capture

Response

Status:
200 OK
{
"id": 1,
"source_type": "Spree::CreditCard",
"source_id": 1,
"amount": "10.00",
"display_amount": "$10.00",
"payment_method_id": 1,
"state": "checkout",
"avs_response": null,
"created_at": "2012-10-24T23:26:23Z",
"updated_at": "2012-10-24T23:26:23Z",
"number": "P58PJCXG"
}

Failed Response

Status:
422 Unprocessable Entity
{
  "error": "There was a problem with the payment gateway: [text]"
}

Purchase

Purchasing a payment is typically done only if you are not authorizing payments before-hand. If you are authorizing payments, then use the authorize and capture endpoints instead.

To make a purchase with a payment, make a request like this:

PUT /api/v1/orders/R1234567/payments/1/purchase

Response

Status:
200 OK
{
"id": 1,
"source_type": "Spree::CreditCard",
"source_id": 1,
"amount": "10.00",
"display_amount": "$10.00",
"payment_method_id": 1,
"state": "checkout",
"avs_response": null,
"created_at": "2012-10-24T23:26:23Z",
"updated_at": "2012-10-24T23:26:23Z",
"number": "P58PJCXG"
}

Failed Response

Status:
422 Unprocessable Entity
{
  "error": "There was a problem with the payment gateway: [text]"
}

Void

To void a payment, make a request like this:

PUT /api/v1/orders/R1234567/payments/1/void

Response

Status:
200 OK
{
"id": 1,
"source_type": "Spree::CreditCard",
"source_id": 1,
"amount": "10.00",
"display_amount": "$10.00",
"payment_method_id": 1,
"state": "checkout",
"avs_response": null,
"created_at": "2012-10-24T23:26:23Z",
"updated_at": "2012-10-24T23:26:23Z",
"number": "P58PJCXG"
}

Failed Response

Status:
422 Unprocessable Entity
{
  "error": "There was a problem with the payment gateway: [text]"
}

Credit

To credit a payment, make a request like this:

PUT /api/v1/orders/R1234567/payments/1/credit?amount=10

If the payment is over the payment’s credit allowed limit, a “Credit Over Limit” response will be returned.

Response

Status:
200 OK
{
"id": 1,
"source_type": "Spree::CreditCard",
"source_id": 1,
"amount": "10.00",
"display_amount": "$10.00",
"payment_method_id": 1,
"state": "checkout",
"avs_response": null,
"created_at": "2012-10-24T23:26:23Z",
"updated_at": "2012-10-24T23:26:23Z",
"number": "P58PJCXG"
}

Failed Response

Status:
422 Unprocessable Entity
{
  "error": "There was a problem with the payment gateway: [text]"
}

Credit Over Limit Response

Status:
422 Unprocessable Entity
{
  "error": "This payment can only be credited up to [amount]. Please specify an amount less than or equal to this number."
}
Propose changes to this page
Maintained bySpree Commerce & Ruby on Rails developers© Spree Commerce. 2021 All Rights Reserved.