Before a transaction can be completed on the front-end it must be registered with SmarterPay and the Payment Gateway. This includes things like the type of transaction, the amount and currency it will be made under. Importantly it will also inform SmarterPay which Payment Gateway Profile will be used for the transaction. Each transaction type has a MOTO or Ecommerce equivalent depending on where the transaction is taking place.
SmarterPay will respond with a set of information that must be passed to SmarterPay.js when initialising the front-end card terminal.
| Method | Purpose |
|---|---|
| POST | Register a new card payment |
Action: Create a new card payment transaction.
Method: POST
URL: https://pay.smarterpay.com/SmarterPayCardPaymentService/api/transaction
Request Parameters
| Property | Mandatory | Description |
|---|---|---|
| payment_gateway_profile_id | True | The Id of the Payment Gateway Profile that this transaction should take place under. |
| payment_type | True | The type of transaction that is being registered. Valid values are 'MOTO','Ecommerce','DeferredMOTO','DeferredEcommerce','AuthenticateMOTO','AuthenticateEcommerce'. |
| platform | True | Always set to 'SmarterPayCloud'. |
| customer_id | True | The Id of the Customer Account that this transaction will be related to. |
| amount | True | Amount of the transaction in the lowest denomination of the currency. No decimal places. For example, send pence if a GBP transaction. |
| currency_code | True | ISO 4217 representation of the currency the transaction should take place in. |
| internal_payment_description | False | A long description of the transaction for internal use only. Not seen by the customer. |
| gateway_payment_description | False | A long description of the transaction that will be forwarded to the Payment Gateway. Depending on the Payment Gateway, this may or may not be seen by the customer. |
| custom_reference | False | Custom reference set on record. |
| metadata | False | Any additional data attached to the transaction. Recommendation to use key/value pairs or simple JSON structures. This will be sent out in any active Webhooks so can be used to tie information back to source records in another platform. |
| use_card_address | False | Set to True if the Card Holder Address is different to the one set on the Customer Account. Default is False. |
| card_holder_address_line1 | False | |
| card_holder_address_line2 | False | |
| card_holder_address_city | False | |
| card_holder_address_postal_code | False | |
| card_holder_address_state_code | False | 2 character US state code. Mandatory if country_code set to “US”. |
| card_holder_address_country_code | False | 2 character Country Code (ISO 3166-1 alpha-2). |
Request Sample
{
"payment_gateway_profile_id": "PG01KO5D0G80MJERW4VQ",
"platform": "SmarterPayCloud",
"payment_type": "MOTO",
"customer_id": "CA01LYZ96J12X48NEWDV",
"amount": 200,
"currency_code": "GBP",
"internal_payment_description":"Payment for something",
"gateway_payment_description":"Payment for something sent to the gateway",
"custom_reference":"MYREFERENCE0001" ,
"metadata": "{\"key1\": \"value1\", \"key2\": \"value2\"}",
"use_card_address": true,
"card_holder_address_line1":"Address Line 1",
"card_holder_address_line2":"Address Line 2",
"card_holder_address_city":"City",
"card_holder_address_postal_code":"XX00 ZZZ",
"card_holder_address_country_code":"GB"
}
Response Parameters
| Property | Description |
|---|---|
| card_id | The ID of the new registered card. |
| customer_id | The ID of the customer account that the card is related to. |
| platform | The platform that the transaction took place on. Always 'SmarterPayCloud'. |
| payment_type | The type of transaction requested. |
| payment_gateway | Confirmation of the Payment Gateway that the transaction is registered under. |
| payment_gateway_data | Configuration data to be sent during initialisation of SmarterPay.js on the front-end. |
Response Sample
{
"card_id": "CD01MQ0KN8XMV7POXZG7",
"customer_id": "CA01LYZ96J12X48NEWDV",
"platform": "SmarterPayCloud",
"payment_type": "MOTO",
"payment_gateway": "OpayoPi",
"payment_gateway_data": "eyJwbGF0Zm9ybSI6IlNtYXJ0ZXJQYXlDbG91ZCIsInBheW1lbnRfZ2F0ZXdheSI6IkFkeWVuIiwiY2FyZF9pZCI6IkNEMDFNUTBLTjhYTVY3UE9YWkc3IiwiaXNfdGVzdCI6dHJ1ZSwiY29tcGxldGVfZW5kcG9pbnQiOiJodHRwczovL3Rlc3QxLnNtYXJ0ZXJwYXkuY29tL0Rldi9TbWFydGVyUGF5Q2FyZFBheW1lbnRTZXJ2aWNlL2FwaS9UcmFuc2FjdGlvbiIsInBheW1lbnRfZ2F0ZXdheV9kYXRhIjoidGVzdF9FV1dFSExaRFpSRlhUSUFZVVpRWkFTVUJZUU9YTzJUTCJ9"
}