97 lines
2.9 KiB
Markdown
97 lines
2.9 KiB
Markdown
# Fonepay Unity
|
|
|
|
Fonepay payment integration for Unity. Request QR codes, await payment confirmation over websocket, process tax refunds — all from a single async-friendly client.
|
|
|
|
## Requirements
|
|
|
|
- Unity 6000.4+
|
|
- [UniTask](https://github.com/Cysharp/UniTask) (for sample only — runtime uses `System.Threading.Tasks`)
|
|
|
|
## Setup
|
|
|
|
1. Install the package via Package Manager (Git URL or local).
|
|
2. Open **Tools > Fonepay > Settings** to create the `FonepayConfig` asset and enter your merchant credentials. Credentials are kept out of source control and baked at build time.
|
|
3. (Optional) **Window > Package Manager > Fonepay Unity > Samples > Import** to drop the example MonoBehaviour into your project.
|
|
|
|
## Usage
|
|
|
|
### 1. Request a QR
|
|
|
|
```csharp
|
|
using Darkmatter.Fonepay;
|
|
|
|
var fonepay = new FonepayClient();
|
|
|
|
QrResult qr = await fonepay.PurchaseAsync(new QrRequest
|
|
{
|
|
amount = 100f,
|
|
remarks1 = "order #1234"
|
|
}, ct);
|
|
|
|
// qr.qrCode is a Texture2D ready to render
|
|
// qr.thirdpartyQrWebSocketUrl — pass to AwaitPaymentAsync
|
|
```
|
|
|
|
### 2. Await payment
|
|
|
|
```csharp
|
|
QRPaymentStatus result = await fonepay.AwaitPaymentAsync(
|
|
qr.thirdpartyQrWebSocketUrl,
|
|
onQrVerified: verified => Debug.Log($"QR scanned: {verified}"),
|
|
ct: ct);
|
|
|
|
switch (result.Outcome)
|
|
{
|
|
case PaymentOutcome.Complete: // success
|
|
case PaymentOutcome.CancelledByUser: // user dismissed in app
|
|
case PaymentOutcome.Failed: // server rejected
|
|
}
|
|
```
|
|
|
|
`AwaitPaymentAsync` opens the websocket, fires `onQrVerified` when the QR is scanned, then resolves on the terminal payment frame and disconnects.
|
|
|
|
### 3. Cancellation & timeout
|
|
|
|
```csharp
|
|
var cts = CancellationTokenSource.CreateLinkedTokenSource(destroyCancellationToken);
|
|
cts.CancelAfter(TimeSpan.FromMinutes(15)); // QR validity
|
|
|
|
try
|
|
{
|
|
var payment = await fonepay.AwaitPaymentAsync(qr.thirdpartyQrWebSocketUrl, ct: cts.Token);
|
|
}
|
|
catch (OperationCanceledException) { /* user cancelled or timed out */ }
|
|
catch (InvalidOperationException) { /* server closed websocket early */ }
|
|
catch (FonepayError e) { /* API error — e.ErrorCode, e.Docs */ }
|
|
```
|
|
|
|
Calling `cts.Cancel()` from a button handler aborts the await and disconnects the socket.
|
|
|
|
### 4. Tax refund
|
|
|
|
```csharp
|
|
TaxRefundResponse refund = await fonepay.PostTaxRefundAsync(new TaxRefundRequest
|
|
{
|
|
fonepayTraceId = "...",
|
|
merchantPRN = "...",
|
|
invoiceNumber = "INV-001",
|
|
invoiceDate = DateTime.UtcNow,
|
|
transactionAmount = 100f,
|
|
}, ct);
|
|
```
|
|
|
|
## Errors
|
|
|
|
`FonepayError` (extends `Exception`) carries `ErrorCode` and `Docs`. Throw paths:
|
|
- Missing/invalid `FonepayConfig` asset or credentials
|
|
- Non-2xx HTTP responses from Fonepay
|
|
- HMAC signing failures
|
|
|
|
## Samples
|
|
|
|
Import **Example Payment Flow** from the Package Manager. Wires a button → QR image → success/fail panels with cancel support.
|
|
|
|
## Tests
|
|
|
|
Editor tests live under `Tests/Editor` (NUnit). Run via **Window > General > Test Runner > EditMode**.
|