Payments: Sale

Modified on Wed, 1 May at 2:04 PM

Sale Transaction

This API endpoint is called in order to charge a customer for a set amount. ACME requires tokenized transactions to remain PCI compliant, so know how to generate or reference a Token.

You will need your MerchantID {mid} and PaymentKey {x-acme-payment-key} to run sales, if you do not have these, please contact your ACME account manager.

After completing the sale you can use the Refund API in order to refund the transaction.

POST v1/payment/{mid}/sale

Request Parameters

The merchant ID of the seller performing the sale.

Request Body

Include a SaleRequest object as the body of the request.

Sample Request Body:

Sample Request Body

Sale by Token

{
  "token" : "123-456-789",
  "charge": {
    "amount" : 50.00
  },
  "externalId": "BSYE623048"
}

Sale by External Payment Method

{
  "externalPaymentMethodId" : "PMID-123",
  "charge": {
    "amount" : 50.00
    "netAmount": "47.90",
                "fee": {
                    "totalFee": "0.80",
                    "fixedFee": "0.43",
                    "percentageFee": "0.37",
                    "percentageRate": "0.50"
                }
  },
  "externalId": "BSYE623048"
}

Sample Request

POST https://sandX-api.acmepayments.net/v1/payment/12345/sale

Response

Returns a SaleResponse object or an error for the failed transaction.

Sample Response Body

Successful Sale Transaction

{
	"saleId": "sale_72a57412-04bf-4803-9667-369cd414a07f",
	"externalId": "extId-QA1234",
	"card":
	{
		"lastFour": "3333",
		"expirationDate":
		{
			"month": "12",
			"year": "2026"
		},
		"brand": "Visa"
	},
	"postalCode": "95555",
	"externalTransactionId": 9876543210098,
	"amount":
	{
		"totalAmount": "2.70",
		"netAmount": "2.32",
		"fee":
		{
			"totalFee": "0.38",
			"fixedFee": "0.30",
			"percentageFee": "0.08",
			"percentageRate": "2.90"
		}
	}
}

Failed Sale Transaction

If the error happens at ACME there will not be a processor or issuing error code. If the error happens at the issuing bank then both of those should be available. If it happens at the payment processor, then there will probably not be an issuing error but there will be a processor error.

{
	"timestamp": "2024-05-01T13:01:04-05:00",
	"message": "The provided Token does not exist",
	"errorCode": 10008,
	"type": "TOKEN_DNE",
	"requestId": "c7142a94-07e4-11ef-8b97-06b5bdd98bb9",
	"path": "/v1/payment/544892d62/sale"
}

SaleRequest Object

Name	Type	Description	Required
token	string	Either a single use or a multi use token	Token or externalPaymentMethodId Required
externalPaymentMethodId	string	Plain text value provided during token creation which represents the token.	Token or externalPaymentMethodId Required
charge	Charge object	The charge object for this sale. The amount is required	Required
externalId	string	Plain text value provided for this sale. Max 255 char. Cannot contain %, <, >, http:, https:, /, \\	Optional

Charge Object

Name	Type	Description	Required
amount	number	The amount of money the sale or refund is for. 2 decimal places are supported	Required

SaleResponse Object

Name	Type	Description
saleId	string	Unique identifier for this transaction
card	Card Object ›	The details of the credit card
externalId	string	Plain text value provided for this sale.
postalCode	string	Postal code used for this transaction
externalTransactionId	string	Plain text value provided for this sale.
amount	Amount Object	total and net amount of the transaction. total and fixed fees, with associated percentages. optional fees are netted out from the total and listed.