Register Transaction

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

POST

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"
}