Card Webhooks
Webhook structure and samples for Cards.
Card Webhook - Structure
{
"events":
[
{
"id" : {EVENTID},
"created_at" : {CREATEDDATE},
"resource_type" : {RESOURCETYPE},
"description" : {DESCRIPTION},
"event_source" : {EVENTSOURCE},
"reference" : {REFERENCE},
"payment_gateway_profile" : {PAYMENTGATEWAYPROFILE},
"customer_account" : {CUSTOMERACCOUNT},
"card_created_at" : {CARDCREATEDAT},
"card_edited_at" : {CARDEDITEDAT},
"custom_reference" : {CUSTOMREFERENCE},
"view_tag" : {VIEWTAG},
"payment_gateway" : {PAYMENTGATEWAY},
"card_type" : {CARDTYPE},
"card_number_ending" : {CARDNUMBERENDING},
"card_expiry_date" : {CARDEXPIRYDATE},
"name_on_card" : {NAMEONCARD},
"internal_payment_description" : {INTERNALPAYMENTDESCRIPTION},
"gateway_payment_description" : {GATEWAYPAYMENTDESCRIPTION},
"gateway_payee_id" : {GATEWAYPAYEEID},
"gateway_card_id" : {GATEWAYCARDID},
"transaction_type" : {TRANSACTIONTYPE},
"status" : {STATUS},
"status_details" : {STATUSDETAILS},
"currency_code" : {CURRENCYCODE},
"initial_amount" : {INITIALAMOUNT},
"metadata" : {METADATA},
"gateway_status" : {GATEWAYSTATUS},
"gateway_status_code" : {GATEWAYSTATUSCODE},
"gateway_status_details" : {GATEWAYSTATUSDETAILS}
}
]
}
Webhooks are sent out of SmarterPay Cloud as a JSON array.
The JSON Syntax Rules are:
- Data is in name/value pairs, for example {“id” : “EV000003432”}.
- Data is separated by commas.
- Curly braces hold objects.
- Square brackets hold arrays.
| Property | Variable | Description | Empty Values (1) | Format | Example |
|---|---|---|---|---|---|
| id | {EVENTID} | The ID of the Webhook Event. | No | String | “EV000003432” |
| created_at | {CREATEDDATE} | The Date that event was created. | No | ISO8601 | “2020-12-22T08:05:00.000Z” |
| resource_type | {RESOURCETYPE} | The Resource type will be cardpayment. | No | String | “cardpayment” |
| description | {DESCRIPTION} | The description of Webhook Event. | No | String | “API - Card Payment inserted” |
| event_source | {EVENTSOURCE} | The Event code that triggered the sending of the Webhook. | No | Integer | “20071000” |
| reference | {REFERENCE} | The unique SmarterPay Id of the card payment. | No | String | “ED3CA3B7-6F63-49DE-B924-C2D50CFB2B50” |
| payment_gateway_profile | {PAYMENTGATEWAYPROFILE} | The gateway identifier that was used for this transaction. | No | String | “1FDB5A98-453A-40D6-9166-1AC89B920468” |
| customer_account | {CUSTOMERACCOUNT} | The Customer Account that the Card belongs to, if set. | Yes | String | “CUST00032041” |
| card_created_at | {CARDCREATEDAT} | The date and time the card was initially registered on SmarterPay. | No | Datetime | “2021-04-15 03:59:50” |
| card_edited_at | {CARDEDITEDAT} | The last date and time the card was modified. | No | Datetime | “2021-04-15 03:59:50” |
| custom_reference | {CUSTOMREFERENCE} | Custom reference supplied by the client. | Yes | String | “Hetfield2934” |
| payment_gateway | {PAYMENTGATEWAY} | The name of the payment gateway used to register the card. | No | String | “OpayoPi” |
| card_type | {CARDTYPE} | The card association for the card. Visa, Amex, etc. | Yes | String | “Visa” |
| card_number_ending | {CARDNUMBERENDING} | Typically the last four digits of the long card number. | Yes | String | “0001” |
| card_expiry_date | {CARDEXPIRYDATE} | The date that the card can no longer be used. | Yes | Date | “2022-12-01” |
| name_on_card | {NAMEONCARD} | The name of the person who owns the card. | Yes | String | “James Hetfield” |
| internal_payment_description | {INTERNALPAYMENTDESCRIPTION} | A description of payment that is only for 'office use' and not shared with a customer. | Yes | String | “Payment from Ecommerce Page” |
| gateway_payment_description | {GATEWAYPAYMENTDESCRIPTION} | A description of payment that is passed onto the gateway and may be shared with the customer. | Yes | String | “” |
| gateway_payee_id | {GATEWAYPAYEEID} | Unique identifier of the payee passed to SmarterPay from the gateway. | Yes | String | “” |
| gateway_card_id | {GATEWAYCARDID} | Unique identifier of the card passed to SmarterPay from the gateway. | Yes | String | “” |
| transaction_type | {TRANSACTIONTYPE} | What type of transaction took place. For example: Ecommerce or MOTO. | No | String | “Ecommerce” |
| status | {STATUS} | SmarterPay's normalised status of the card. | No | String | “pending” |
| status_details | {STATUSDETAILS} | SmarterPay's additional information based on the status. | Yes | String | “” |
| currency_code | {CURRENCYCODE} | ISO 4217 representation of the currency used for the card payment. | No | ISO4217 | “GBP” |
| initial_amount | {INITIALAMOUNT} | The amount initially charged to the card. | No | Decimal | 12.45 |
| metadata | {METADATA} | Additional client JSON initially passed in the card registration request that is sent with every webhook. | Yes | String | “” |
| gateway_status | {GATEWAYSTATUS} | The status of the card passed by the gateway to SmarterPay. | Yes | String | “Ok” |
| gateway_status_code | {GATEWAYSTATUSCODE} | A code that the gateway may pass to SmarterPay to further describe the status. | Yes | String | “0000” |
| gateway_status_details | {GATEWAYSTATUSDETAILS} | Additional information, based on the status, passed by the gateway to SmarterPay. | Yes | String | “The Authorisation was Successful.” |
Notes:
(1) Empty Values - The property will always be in the Webhook, however the value of the property may be an empty string (“”).