The most simple form of integration with AddPay, once-off AddPay Hosted transactions:
- Create a transaction object with the required fields: reference, description and amount
- Create a customer object with the required fields: firstname, lastname, email, mobile
- Associate the customer object to the transaction
- Redirect the customer to the URL returned in the transaction object's direct field.
- The customer will be returned to your configured return_url (configured in your account settings or per transaction) at which point you can:
a) Use the transaction get API to retrieve the transaction object using its ID and interrogate the status and state fields for the result
b) Interrogate the status and state fields of the payload sent to your notify_url (configured in your account settings or per transaction)
c) Retrieve the event object from the Events API
1. Create the Transaction container
Using the Transactions API, create a new transaction object. This will return an a field named direct, which contains a value which is a URL to the AddPay Hosted Payment page for the particular transaction, this is the URL we will use to redirect the customer once we've defined all dependencies.
2. Create the Customer or use an Existing Customer
If you have previously created a customer object, you can simply skip this step and associate the customer ID to the transaction in step 3, otherwise we need to prepare a customer object:
Using the Customers API, create a customer object, the response payload will return an ID, we will use this ID to associate the customer to the transaction object we're about to create.
3. Associate the Customer to the Transaction
Using the Transactions API, associate the customer object to the transaction using the transaction ID and customer ID we received in the previous steps.
4. Redirect the Customer
At this point you should have a fully configured transaction object that contains a customer object, amount, reference and description. Along with the payload you will receive an attribute named direct, this is the URL that the customer must be redirected to where they will process their transaction using the payment method of their choosing (depending on the services associated to your merchant account). The customer may process or cancel the payment at any time at which point they will be returned to the merchant's configured return_url where the reconciliation and/or parsing of the transaction result should be done, see step 5.
5. Interrogate the Response Payload & Read the Result
The API allows you to parse the result of a transaction in three ways:
a) Interrogate the transaction object using the Get Single Transaction call described in the Transactions API when the customer is redirected from the AddPay payment page to your configured return_url.
b) If the merchant has a configured notify_url (configured on the merchant console under account options), events will be fired to the provided URL whenever the transaction status changes, this means you can handle the result of a transaction behind the scenes before the customer has even been redirected back to your configured return_url.
c) Similarly to firing events to the merchants configured notify_url, the Events API allows you to look up events if your server was unable to receive the event for any reason. See the Events API for more information.