List of Messages - academe/SagePay GitHub Wiki
Messages go in both directions (between the library and SagePay site, as initiating requests and callbacks). Each message is a POST, and has parameters. Each POST has a response, and that also has parameters. This page aims to list those messages so that we can:
- Give each message a name.
- Update the metadata with details of the fields.
Documentation from SagePay is spread over a number of sections of multiple documents. We would like to gather it all together in one place (the metadata file) so that the raw data can help drive the processes with the minimum of hard-coding. Once assumption we are relying on, is that the transaction consists of a subset of a large set of fields. No field is used for multiple purposes or has different properties at different times. Each message will take some of these fields and pass them to the opposite system in each API call.
The number of each message is the appendix number in the documentation.
The name of each message is the name used in the metadata of this library to link fields to a message.
SagePay Server Method
This method uses the fewest messages.
| Number | Name | Direction | POST Service | Name |
|---|---|---|---|---|
| A1 | Server Transaction Registration | site->SagePay | PAYMENT, DEFERRED, AUTHENTICATE | server-registration |
| A2 | Server Transaction Registration Response | SagePay->site | Response to A1 | server-registration-response |
| A3 | Server Transaction Callback | SagePay->site | PAYMENT, DEFERRED, AUTHENTICATE | server-notification |
| A4 | Server Transaction Callback Response | site->SagePay | Response to A3 | server-notification-response |
SagePay Direct Method
In theory this should involve fewer messages as there should be less reason to send the user to third-party sites. However, with 3DSecure and SagePay redirects then being pulled into the application, rather than being handled by SagePay in a single call - effectively wrapping that functionality up into a black box - the SagePay Direct method involves many more messages.
| Number | Name | Direction | POST Service | Name |
|---|---|---|---|---|
| A1 | Direct Transaction Registration | site->SagePay | PAYMENT, DEFERRED, AUTHENTICATE | direct-registration |
| A2 | Direct Transaction Registration Final Response | SagePay->site | Response to A1, A4 or A8 | direct-final-response |
| A3 | Direct Transaction Registration 3DSecure Response | SagePay->site | Response to A1 | direct-3dauth-response |
| ? | Redirect to Card Issuer 3D Auth | site->CardIssuer | Client-side POST to ACSURL from A3 | direct-3dauth-issuer |
| ? | Return from Card Issuer | CardIssuer->site | POST | direct-3dauth-issuer-return |
| A4 | 3DSecure Authentication Result | site->SagePay | POST, no service name | direct-3dsecure-callback |
| A5 | 3DSecure Authentication Result Response | SagePay->site | Response to A4, identical to A2 | direct-3dsecure-callback-response |
| A6 | Direct Transaction Registration PayPal Response | SagePay->site | Response to A1 | direct-paypal-response |
| A7 | PayPal Post-Authentication Callback | SagePay->site | POST, no service name | ? |
| ? | PayPal Post-Authentication Callback Response | site->SagePay | see notes below | direct-paypal-callback |
| A8 | PayPal Complete | site->SagePay | COMPLETE | ? |
| ? | PayPal Complete Response | SagePay->site | Response to A8, identical to A2 | ? |
The A7 message is descried as a callback in the documentation, but shown as a client redirect in the flow diagram. A7 cannot be sent in a redirect without encrypting the data in the URL, and that is not mentioned. I suspect something is mislabelled or simply missing in the documentation. Update: for 3DSecure transactions, some of the POSTs are client-side, using automatically-submitted forms. Consequently that is viewed as a callback, but viewed from the perspective of the card issuing bank and not the website. I'll update the above table and description with this in mind, shortly.
The SagePay response to an A1 message will be A2, A3 or A6, depending on the details sent in A1 (i.e. whether the card type is SagePay or not, and whether 3DSecure was requested or not).
Shared Method Messages
A handful of messages are used by both SagePay Server and SagePay Direct, and operate in the same way for both methods.
| Number | Name | Direction | POST Service | Name |
|---|---|---|---|---|
| A1 | RELEASE | site->SagePay | RELEASE | shared-release |
| A2 | RELEASE Response | SagePay->site | Response to A1 | shared-release-response |
| A3 | ABORT | site->SagePay | ABORT | shared-abort |
| A4 | ABORT Response | SagePay->site | Response to A3 | shared-abort-response |
| A5 | REFUND | site->SagePay | REFUND | shared-refund |
| A6 | REFUND Response | SagePay->site | Response to A5 | shared-refund-response |
| A7 | REPEAT/REPEATDEFERRED | site->SagePay | REPEAT/REPEATDEFERRED | shared-repeat |
| A8 | REPEAT/REPEATDEFERRED Response | SagePay->site | Response to A7 | shared-repeat-response |
| A9 | VOID | site->SagePay | VOID | shared-void |
| A10 | VOID Response | SagePay->site | Response to A9 | shared-void-response |
| A11 | MANUAL | site->SagePay | MANUAL | shared-manual |
| A12 | MANUAL Response | SagePay->site | Response to A11 | shared-manual-response |
| A13 | DIRECTREFUND | site->SagePay | DIRECTREFUND | shared-refund |
| A14 | DIRECTREFUND Response | SagePay->site | Response to A13 | shared-refund-response |
| A15 | AUTHORISE | site->SagePay | DIRECTREFUND | shared-authorise |
| A16 | AUTHORISE Response | SagePay->site | Response to A15 | shared-authorise-response |
| A17 | CANCEL | site->SagePay | DIRECTREFUND | shared-cancel |
| A18 | CANCEL Response | SagePay->site | Response to A17 | shared-cancel-response |
A few of these responses are in the same format: the protocol version, status code and status message, but most are different to cater for additional information that the service needs to return.