Account Groups allow a single payment plugin session to process multiple charges using the Charge Set endpoint in the Payments API.
In order to use Charge Sets the payment plugin needs to know the details of
each charge. The account_groups and line_items properties of the Create
Payment Plugin request are used to define this.
Here is a sample payload that demonstrates the use of Account Groups:
{
"account_id": "pa_05cc856bfafc92a2b0832d060y7gGkaztPUNDRsoPwRI9m",
"invoice_number": "123",
"po_number": "ABC",
"amount": 50,
"payment_methods": {
"card": {
"allowed": true
},
"bank_account": {
"allowed": true
}
},
"account_groups": [
{
"id": "1",
"account_id": "pa_02am2d06e04180939c039bf2eKebdXgdOMYykaBwEJ9Sza",
"invoice_number": "456",
"po_number": "DEF",
"tax_amount": 1.61
},
{
"id": "2",
"account_id": "pa_02am2d06e04180939c039bf2eKebdXgdOMYykaBwEJ9Sza",
"invoice_number": "789",
"po_number": "GHI"
}
],
"line_items": [
{
"account_group_id": "1",
"description": "Line item 1",
"quantity": 1,
"unit_cost": 13,
"line_item_amount": 13
},
{
"account_group_id": "1",
"description": "Line item 2",
"quantity": 1,
"unit_cost": 10,
"line_item_amount": 10
},
{
"account_group_id": "2",
"description": "Line item 3",
"quantity": 3,
"unit_cost": 4.5,
"line_item_amount": 13.5
},
{
"description": "Line item 4",
"quantity": 3,
"unit_cost": 4.5,
"line_item_amount": 13.5
}
],
"convenience_fee": {
"card": [
{
"percent": 3,
"fixed": 0.2
}
],
"bank_account": [
{
"percent": 0.5,
"fixed": 0.2
}
]
}
}Let's examine each property in this payload.
account_id, invoice_number, po_number - These properties at the request's
root level set the default values that will be used on the default charge in the
Charge Set.
amount - The total payment amount that will be processed when all charges in
the Charge Set are added up.
payment_methods - Defines the payment method types that will be accepted.
account_groups - Two account groups are defined.
account_groups[0] - The first account
group has been assigned an arbitrary id of 1. The definition of this first
account group overrides the default account_id to process through a different
merchant account. It also changes the invoice_number and po_number that will
be set on the charge. Finally, it sets a specific tax_amount. When using
Account Groups any tax amount must be specified in the tax_amount of the
Account Groups.
account_groups[1] - The second account group has been assigned an arbitrary
id of 2. The definition of this second account group also overrides the
default account_id to process through a different merchant account. Note that
this Account Group uses the same account_id as account_groups[0]. This
results in two different charges being processed through the same merchant
account. It also changes the invoice_number and po_number that will
be set on the charge. Finally, it sets a specific tax_amount.
line_items - Defines line items that will be added to the
charges in the Charge Set. They also define how line items are grouped to make
individual charges in the Charge Set by setting an account_group_id. Any
line items that have the same account_group_id value will have their amount
added together and processed as a single charge within the Charge Set using
the settings specified for the referenced Account Group in account_groups.
The sample Payment Plugin Session above results in the following Charge Set being processed:
{
"rollback": true,
"charges": [
{
"account_id": "pa_02am2d06e04180939c039bf2eKebdXgdOMYykaBwEJ9Sza",
"payment_method": {
"card_number": "************1111",
"cvv": "412",
"expiration_date": "1222",
"contact": {
"first_name": "John",
"last_name": "Doe",
"address1": "500 Oak Street",
"city": "Somewhere",
"state": "MN",
"postal_code": "56000"
}
},
"invoice_number": "456",
"po_number": "DEF",
"tax_amount": 1.61,
"total_amount": 25.37,
"convenience_fee": 0.76
},
{
"account_id": "pa_02am2d06e04180939c039bf2eKebdXgdOMYykaBwEJ9Sza",
"payment_method": {
"card_number": "************1111",
"cvv": "412",
"expiration_date": "1222",
"contact": {
"first_name": "John",
"last_name": "Doe",
"address1": "500 Oak Street",
"city": "Somewhere",
"state": "MN",
"postal_code": "56000"
}
},
"invoice_number": "789",
"po_number": "GHI",
"tax_amount": 0,
"total_amount": 13.94,
"convenience_fee": 0.44
},
{
"account_id": "pa_05cc856bfafc92a2b0832d060y7gGkaztPUNDRsoPwRI9m",
"payment_method": {
"card_number": "************1111",
"cvv": "412",
"expiration_date": "1222",
"contact": {
"first_name": "John",
"last_name": "Doe",
"address1": "500 Oak Street",
"city": "Somewhere",
"state": "MN",
"postal_code": "56000"
}
},
"invoice_number": "123",
"po_number": "ABC",
"tax_amount": 0,
"total_amount": 13.94,
"convenience_fee": 0.44
}
]
}charges[0] - This charge was generated from the Account Group with an id of
1. The first two line_items[] reference "account_group_id": "1" causing
them to be grouped together in a single charge. The first line item had an
amount of $13.00. The second line item had an amount of $10.00. The Account
Group has a tax specified of $1.61. Finally, this charge received the
proportional convenience fee amount of $0.76. Added all up the first charge was
for a total of $25.37. The Account Group also had invoice_number and
po_number set which overrode the default settings for these properties.
charges[1] - This charge was generated from the Account Group with an id of
2. The third line item references "account_group_id": "2" causing
it to generate this charge. The line item has a total of $13.50. The charge
has the proportional convenience fee of $0.44 added to it. Added up the total
amount for this charge is $13.94. The Account Group also had invoice_number and
po_number set which overrode the default settings for these properties.
charges[2] - This charge was generated by the last line item which did not
reference an Account Group. As a result it used the default values for
account_id, invoice_number, and po_number specified at the root level of
the payment plugin request. The line item has a total of $13.50 and has the
proportional convenience fee of $0.44 added to it. This results in a total
charge of $13.94. In this case it is processed through a different merchant
account than the other two charges.
Your hosting page will receive a different payload when a Charge Set is successfully processed. Here is the event object for the above sample Charge Set:
{
"charge_set_id": "629e465d92483535c9ec9af0",
"charge_type": "sale",
"amount": "50.00",
"convenience_fee": "1.70",
"supplemental_fee": "0.00",
"total_amount": "53.31",
"tax_amount": "1.61",
"fields": {
"contact": {
"first_name": "John",
"last_name": "Doe",
"address1": "500 Oak Street",
"city": "Somewhere",
"state": "MN",
"postal_code": "56000"
},
"card_number": "************1111",
"expiration_date": "1222",
"card_type": "visa",
"card_type_display": "Visa",
"payment_method_description": "Visa **1111"
},
"charges": [
{
"status": "success",
"authorization_code": "ilByAH85",
"amount": "24.61",
"convenience_fee": "0.76",
"tax_amount": "1.61",
"total_amount": "25.37",
"processor_messages": {
"avs_response": "passed",
"cv_response": "passed"
}
},
{
"status": "success",
"authorization_code": "OwJAIUDu",
"amount": "13.50",
"convenience_fee": "0.44",
"total_amount": "13.94",
"processor_messages": {
"avs_response": "passed",
"cv_response": "passed"
}
},
{
"status": "success",
"authorization_code": "RN5FCrcu",
"amount": "13.50",
"convenience_fee": "0.44",
"total_amount": "13.94",
"processor_messages": {
"avs_response": "passed",
"cv_response": "passed"
}
}
]
}charge_set_id - A unique identifier of the Charge Set that was created.
charges[] - An array of charges that make up the Charge Set that was created.
charges[].status - If the Payment Plugin session has a setting of
"rollback": false then it is possible to have some charges succeed and others
fail. In this case you will need to examine the status property of all
charges[] items. Any charge that has a status of success was proceseed.
Any charge with any status value other than success failed.