Payments
Index
To see details about an order’s payments, make this request:
GET /api/v1/orders/R1234567/paymentsPayments are paginated and can be iterated through by passing along a page parameter:
GET /api/v1/orders/R1234567/payments?page=2Parameters
- page:
The page number of payments to display.
- per_page:
The number of payments to return per page
Response
{"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]=123The 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
{"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%20descNew
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/newResponse
{
"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]=10Response
{"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/1Response
{"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/authorizeResponse
{"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
{
"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/captureResponse
{"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
{
"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/purchaseResponse
{"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
{
"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/voidResponse
{"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
{
"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=10If the payment is over the payment’s credit allowed limit, a “Credit Over Limit” response will be returned.
Response
{"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
{
"error": "There was a problem with the payment gateway: [text]"
}Credit Over Limit Response
{
"error": "This payment can only be credited up to [amount]. Please specify an amount less than or equal to this number."
}