@acmeticketing/payment-sdk 中文文档教程
ACMEPayments SDK
借助 ACME Payments,您现在可以通过在线支付获利并与 ACME 支付处理平台集成。
可以与您现有的在线结帐流程集成或将卡片展示支付构建到您的 Web 应用程序中。
Installation
ES Module
- Intended for use with modern bundlers like webpack.
- This is the recommended approach and will provide the best developer experience.
npm install @acmeticketing/payment-sdk
UMD
UMD 构建可以通过 标签直接在浏览器中使用。
手动将
payment-sdk.umd.js
脚本标记添加到您网站的 。
<!-- Somewhere in your site's <head> -->
<script src="TBD" async></script>
Usage (ES Module)
所有示例也适用于 UMD 版本,但不是将我们的库作为 ES 模块导入,而是在全局
ACME
对象下可用。
window.ACME.ACMEPayments.init({
publishableKey: 'your_publishable_key',
mid: 'your_mid',
}).then((acmePayments) => {
// Use the `ACMEPayments` instance
const terminal = acmePayments.createTerminal({
onUnexpectedReaderDisconnect: (event) => {
console.log('onUnexpectedReaderDisconnect', event);
},
});
});
Create an ACMETerminal
创建 ACMETerminal
的实例是一个简单的过程,请按照下列步骤操作:
- Use your provided publishable key and merchant identification number (MID).
- Create a new instance of
ACMETerminal
您可以提供一些回调来通知读者的状态等。
import { ACMEPayments, ACMETerminal } from '@acmeticketing/payment-sdk';
async function createACMETerminal(): Promise<ACMETerminal> {
const acmePayments = await ACMEPayments.init({
publishableKey: 'your_publishable_key',
mid: 'your_mid',
});
const terminal = acmePayments.createTerminal({
// This callback is required, `createTerminal` will throw an error if you forget to pass it.
onUnexpectedReaderDisconnect: (event) => {},
onConnectionStatusChange: (event) => {},
onPaymentStatusChange: (event) => {},
});
return terminal;
}
Making a sale
此示例假设您已经初始化了
ACMEPayments
SDK 并创建了一个ACMETerminal
实例。
在进行销售之前,您必须与读者建立有效联系。
只有在您第一次想要进行销售时才需要与您的读者建立联系。 可以通过相同的连接进行进一步的销售。
过程如下:
- Get a list of available readers
- Connect to a reader from the list
- Make your sale
import { ACMETerminal, Sale } from '@acmeticketing/payment-sdk';
async function processSale(acmeTerminal: ACMETerminal): Promise<Sale> {
try {
const readers = await acmeTerminal.discoverReaders();
const reader = readers[0];
await acmeTerminal.connectReader(reader);
const response = await acmeTerminal.sale({
charge: { amount: '3.5' },
});
return response;
} catch (error) {
// handle error
}
}
Processing a refund
此示例假设您已经初始化了
ACMEPayments
SDK 并创建了一个ACMETerminal
实例。
- This will not prompt on the reader. It will process the refund back to the card used for payment.
- We support partial refunds.
import { ACMETerminal, Refund } from '@acmeticketing/payment-sdk';
async function processRefund(acmeTerminal: ACMETerminal): Promise<Refund> {
try {
const readers = await acmeTerminal.discoverReaders();
const reader = readers[0];
await acmeTerminal.connectReader(reader);
const response = await acmeTerminal.refund({
saleId: 'your_sale_id',
charge: { amount: '3' },
});
return response;
} catch (error) {
// handle error
}
}
ACMEPayments SDK
With ACME Payments, you can now monetize online payments and integrate with the ACME payment processing platform.
It's possible to integrate with your existing online checkout flow or build card present payments into your web application.
Installation
ES Module
- Intended for use with modern bundlers like webpack.
- This is the recommended approach and will provide the best developer experience.
npm install @acmeticketing/payment-sdk
UMD
UMD builds can be used directly in the browser via a <script>
tag. Manually add the payment-sdk.umd.js
script tag to the <head>
of your site.
<!-- Somewhere in your site's <head> -->
<script src="TBD" async></script>
Usage (ES Module)
All of the examples also apply to the UMD version but instead of importing our library as an ES Module it will be available under the global
ACME
object.
window.ACME.ACMEPayments.init({
publishableKey: 'your_publishable_key',
mid: 'your_mid',
}).then((acmePayments) => {
// Use the `ACMEPayments` instance
const terminal = acmePayments.createTerminal({
onUnexpectedReaderDisconnect: (event) => {
console.log('onUnexpectedReaderDisconnect', event);
},
});
});
Create an ACMETerminal
Creating an instance of ACMETerminal
is a simple process, follow these steps:
- Use your provided publishable key and merchant identification number (MID).
- Create a new instance of
ACMETerminal
You can provide some callbacks to be notified of your reader's status among other things.
import { ACMEPayments, ACMETerminal } from '@acmeticketing/payment-sdk';
async function createACMETerminal(): Promise<ACMETerminal> {
const acmePayments = await ACMEPayments.init({
publishableKey: 'your_publishable_key',
mid: 'your_mid',
});
const terminal = acmePayments.createTerminal({
// This callback is required, `createTerminal` will throw an error if you forget to pass it.
onUnexpectedReaderDisconnect: (event) => {},
onConnectionStatusChange: (event) => {},
onPaymentStatusChange: (event) => {},
});
return terminal;
}
Making a sale
This example assumes you have already initialized the
ACMEPayments
SDK and obtained created an instance ofACMETerminal
.
Before making a sale you MUST have an active connection to a reader.
Establishing connection with your reader is only required the first time you want to make a sale. Further sales can be made over the same connection.
The process goes like this:
- Get a list of available readers
- Connect to a reader from the list
- Make your sale
import { ACMETerminal, Sale } from '@acmeticketing/payment-sdk';
async function processSale(acmeTerminal: ACMETerminal): Promise<Sale> {
try {
const readers = await acmeTerminal.discoverReaders();
const reader = readers[0];
await acmeTerminal.connectReader(reader);
const response = await acmeTerminal.sale({
charge: { amount: '3.5' },
});
return response;
} catch (error) {
// handle error
}
}
Processing a refund
This example assumes you have already initialized the
ACMEPayments
SDK and obtained created an instance ofACMETerminal
.
- This will not prompt on the reader. It will process the refund back to the card used for payment.
- We support partial refunds.
import { ACMETerminal, Refund } from '@acmeticketing/payment-sdk';
async function processRefund(acmeTerminal: ACMETerminal): Promise<Refund> {
try {
const readers = await acmeTerminal.discoverReaders();
const reader = readers[0];
await acmeTerminal.connectReader(reader);
const response = await acmeTerminal.refund({
saleId: 'your_sale_id',
charge: { amount: '3' },
});
return response;
} catch (error) {
// handle error
}
}