Payment Orders
Overview
The Payment Orders API simplifies the Highnote acquiring offering by letting you easily define items for a PaymentOrder and enabling Highnote to manage the payment flow.
Create a payment order
A payment order can be created using createPaymentOrder. This mutation takes catalogItems which are pre-defined by Highnote for your merchant. These items have pre-defined names, descriptions, and amounts. All pre-defined data can be overwritten when invoking the mutation.
catalogItems can take paymentInstructions which define and automate disbursement regarding which accounts get what amounts. Payment Instructions can be defined to disburse a specific amount or a percentage of the item's amount. They also require a disburseToId (i.e., a Highnote Node ID) to disburse funds to. Currently only a FinancialAccount ID can be used.>
CreatePaymentOrderWithPaymentInstructions
Query
mutation CreatePaymentOrderWithPaymentInstructions(
$input: CreatePaymentOrderInput!
) {
createPaymentOrder(input: $input) {
... on PaymentOrder {
__typename
id
totalAmount {
__typename
value
currencyCode
decimalPlaces
}
lineItems {
item {
__typename
... on PaymentOrderItemFromCatalogItem {
catalogItem {
id
name
description
}
name
description
amountPerItem {
__typename
value
currencyCode
decimalPlaces
}
}
}
quantity
}
}
}
}
Variables
{ "input": { "catalogItems": [ { "id": "acqca_1", "name": "Apple", "description": "A delicious red apple", "amountPerItem": { "value": 100, "currencyCode": "USD" }, "paymentInstructions": [ { "disbursementPercent": 100, "disburseToId": "ac_apple_seller" } ], "quantity": 1 }, { "id": "acqca_2", "name": "Orange", "description": "A juicy orange bursting with flavor", "amountPerItem": { "value": 100, "currencyCode": "USD" }, "paymentInstructions": [ { "disbursementPercent": 100, "disburseToId": "ac_orange_seller" } ], "quantity": 1 } ], "idempotencyKey": "UUID_v4" } }
Result
{
"data": {
"createPaymentOrder": {
"__typename": "PaymentOrder",
"id": "acqor_1",
"totalAmount": {
"__typename": "Amount",
"value": 200,
"currencyCode": "USD",
"decimalPlaces": 2
},
"lineItems": [
{
"item": {
"__typename": "PaymentOrderItemFromCatalogItem",
"catalogItem": {
"id": "acqca_1",
"name": "Apple",
"description": "A delicious red apple"
},
"name": "Apple",
"description": "A delicious red apple",
"amountPerItem": {
"__typename": "Amount",
"value": 100,
"currencyCode": "USD",
"decimalPlaces": 2
}
},
"quantity": 1
},
{
"item": {
"__typename": "PaymentOrderItemFromCatalogItem",
"catalogItem": {
"id": "acqca_2",
"name": "Orange",
"description": "A juicy orange bursting with flavor"
},
"name": "Orange",
"description": "A juicy orange bursting with flavor",
"amountPerItem": {
"__typename": "Amount",
"value": 100,
"currencyCode": "USD",
"decimalPlaces": 2
}
},
"quantity": 1
}
]
}
}
}
Charge a payment order with a payment method token
Once the payment order has been created, a request to charge a PaymentMethodToken (generated from the Checkout SDK) can proceed by using chargePaymentOrderFromPaymentMethodToken. This mutation returns both the payment order charged and a new PaymentTransaction charging the token for the payment order amount.
ChargePaymentOrderPaymentMethodToken
Query
mutation ChargePaymentOrderPaymentMethodToken(
$input: ChargePaymentOrderPaymentMethodTokenInput!
) {
chargePaymentOrderFromPaymentMethodToken(input: $input) {
... on CardCapturePaymentOrderSummary {
transaction {
requestedAuthorizationAmount {
__typename
value
currencyCode
decimalPlaces
}
}
order {
__typename
id
totalAmount {
__typename
value
currencyCode
decimalPlaces
}
lineItems {
item {
__typename
name
description
amountPerItem {
__typename
value
currencyCode
decimalPlaces
}
}
quantity
}
}
}
}
}
Variables
{ "input": { "paymentMethodTokenId": "tkpmc_1", "orderId": "acqor_1", "merchantAcceptorId": "acqma_01", "idempotencyKey": "UUID_v4", "paymentInitiator": "CUSTOMER_INITIATED_VIA_WEB" } }
Result
{
"data": {
"chargePaymentOrderFromPaymentMethodToken": {
"transaction": {
"requestedAuthorizationAmount": {
"__typename": "Amount",
"value": 200,
"currencyCode": "USD",
"decimalPlaces": 2
}
},
"order": {
"__typename": "PaymentOrder",
"id": "acqor_1",
"totalAmount": {
"__typename": "Amount",
"value": 200,
"currencyCode": "USD",
"decimalPlaces": 2
},
"lineItems": [
{
"item": {
"__typename": "PaymentOrderItemFromCatalogItem",
"name": "Apple",
"description": "A delicious red apple",
"amountPerItem": {
"__typename": "Amount",
"value": 100,
"currencyCode": "USD",
"decimalPlaces": 2
}
},
"quantity": 1
},
{
"item": {
"__typename": "PaymentOrderItemFromCatalogItem",
"name": "Orange",
"description": "A juicy orange bursting with flavor",
"amountPerItem": {
"__typename": "Amount",
"value": 100,
"currencyCode": "USD",
"decimalPlaces": 2
}
},
"quantity": 1
}
]
}
}
}
}
View a payment order
A PaymentOrder can be queried using the node query, which lists any PaymentTransactions associated with the PaymentOrder.
PaymentOrder
Query
query PaymentOrder($id: ID!) {
node(id: $id) {
... on PaymentOrder {
totalAmount {
__typename
value
currencyCode
decimalPlaces
}
transactions {
__typename
id
settledAmount {
__typename
value
currencyCode
decimalPlaces
}
refundedAmount {
__typename
value
currencyCode
decimalPlaces
}
}
}
}
}
Variables
{
"id": "acqor_1"
}
Result
{
"data": {
"node": {
"totalAmount": {
"__typename": "Amount",
"value": 200,
"currencyCode": "USD",
"decimalPlaces": 2
},
"transactions": [
{
"__typename": "PaymentDebitTransaction",
"id": "acqpt_1",
"settledAmount": {
"__typename": "Amount",
"value": 200,
"currencyCode": "USD",
"decimalPlaces": 2
},
"refundedAmount": null
},
{
"__typename": "PaymentCreditTransaction",
"id": "acqpt_2",
"settledAmount": null,
"refundedAmount": {
"__typename": "Amount",
"value": 200,
"currencyCode": "USD",
"decimalPlaces": 2
}
}
]
}
}
}