Payment model

Details on Groovs model to help you understand the data and how to maximise the integration benefits

Payment data dictionary


What is a Payment object on Groov platform?


Payment represent the actual transaction when a customer (seller's buyer) gets charged for a purchase using various payment methods. Refunds are recorded as negative payments and will have the reference of the actual purchase payment record. This object allows you to calculate gross sales, Annual Recurring Revenue, Average Revenue Per User, Win Rate, Conversion Rate, Average Deal Size, Average Profit Margin. 

If a payment has been initiated via an invoice request, the payment object will have a link to the Invoice object. 

If a payment has a customer record associated at the point of checkout, the payment object will have a link to the customer object

If a payment has been generated on the back of a customer order on the commerce platform, the payment object will have a link to the order object and will specify details of the product and catalog.


Data Dictionary

AttributeTypeDescription
objectstringvalue is "payment"
idstringidentifier of the payment record on Groov platform
ledgerAccountIdstringid of the merchant account ledger entry as setup on Groov platform.
partnerSourcestringname of the partner system which holds the account name
typestringIf the payment is a charge or a refund.
Values:
charge
refund
amountintegerpayment amount
refund_reasonstringReason for the refund if available. Values can be:
duplicate
fraudulent
requested_by_customer
expired_uncaptured_charge
currencycurrencyThree-letter ISO currency code representing the default currency in which the payment record was captured
transactionstringidentifier of the transaction record on Groov platform that reflects this payment amount. This expansion oject also holds the details of the fees and charges that the commerce/payment provider has applied during processing the payment.

Expansion supported on this attribute
order_id
If a payment has been taken as part of an order on the commerce/payment provider platform, this will hold the details of the order

Expansion supported on this attribute
statusstringstatus of the payment:

unknown
pending
failed
succeeded
cancelled
status_reasonhashdetails of payment status whether the payment was accepted, and why
outcomestringdetailed status of the payment, provides additional information whilst the payment got processed successfully or with exception
unknown
pending
issuer declined
blocked
authorised
paid
failed
cancelled
succeeded
outcome_reasonstringDetails the possible reason why a payment status has been on an exception mode instead of paid. Will show values if provided by the partner

Possible values:
- as per valies in decline_codes column in worksheet "payments_decline_codes"
- lost_or_stolen_card
- expired_or_canceled_card
- unknown
outcome_risk_levelstringTransactional risk value attributed to the payment by the payment provider during authorisation. Defaults to 'Not Available'. If a value is available, it indicates the risk and fraud rating the payment processor has applied on the payment as part of the authorisation process

Values:
Not Available
Not Accessed
Unknown
LowRisk
High Risk
customerstringThis holds the details of the associated customer (buyer) who has made the payment (charge or refund) if available at the point of checkout. This relates to a recordon te Groov ' Customer' data model object.

Expansion supported on this attribute
disputedbooleanIndicates if a charge payment record has been disputed by the customer (buyer)
payment_failure_reason_codestringError code explaining reason if a charge (a type of payment) has failed for some reason whilst in the authorisation/clearing process
payment_failure_reasonstringError description explaining reason if a charge (a type of payment) has failed for some reason whilst in the authorisation/clearing process
fraud_outcomestringFew commerce/payment providers perform  fraud check on few payments (charges) as it goes theorugh the payment processing cycle. If provided, the values will be: safe or fraudulent
invoicestringThis holds the details of the associated invoice that has been generated for the customer (buyer) to facilitate a payment (charge or refund) if available, applies only to those businesses who generate invoices to get paid. This relates to a recordon te Groov's  'Invoice data model object.

Expansion supported on this attribute
method_detailshashProvide additional metadata for the payment method and details used to process the payment
typestring

Payment method type:
card
card_present - only for Stripe where Stripe terminals are used
stripe_account
unknown
cash
custom
invoice
mobile
storecredit
paypal
prepaid

(any others as provided by payment partner)

detailsarray of hashesFor each payment.method_details.type, the details as a hash array subobject specifies the name/value pair of the specific type via which the payment has been made
     type_namestring

for a specific partner, if the payment type has associated details, this stores the name part of the name:value pair (example will be brand, card type, card expiry date, cvc checks performed, etc). Tags that can be queried upon are:

brand
network
funding
last4: contains the last 4 digits of the PAN
card_number: maps to last4 or to the PAN as per info made available by the payment partner
payment_type
entry_mode
payment_type_entry_detail
verification_method
dcc
cross_border_indicator
moto_ecomm_indicator
installment
installment_term

     type_valuestringfor a specific partner, if the payment type has associated details, this stores the value part of the name:value pair for every specific name (example for a type name of Brand, this will show the brand value i.e mastercard or visa, etc)
due_date
Specifies a due date by when the seller has requested for a payment to be made from the customer (buyer). This will be avaialble if provided by the partner
created_datetimestampDate the payment was created in the commerce or partner platform
source_modified_datetimestampDate the payment was last changed in the commerce or partner platform
modifiedDatedateDate the record was last updated in the our system.
pos_terminal_idstringreader or terminal id (TID) of the reader which was used to process the payment if it’s a in person payment (not applicable for eCommerce payments)
location_latitudestringLatitude value from the coordinates of the payment location (as received from the payment terminal reader). - not applicable for eCommerce payments
location_longitudestringLongitude value from the coordinates of the payment location (as received from the payment terminal reader).  - not applicable for eCommerce payments
verification_methodstringVerification method used for the payment during checkout. Possible values are:
none
signature
offline pin
online pin
offline pin + signature
confirmation code verified
unknown


Access our Swagger documentation here







On this page:


Related pages