# Payments (/docs/products/dash-dots/reference/dash-api/payments) ## `dash.payments.request` ```ts dash.payments.request(options: PaymentOptions, callOptions?: PaymentCallOptions): DashRequest ``` Opens Dash's payment sheet, where the person pays for `order` with one of `methods`. The money goes to the Space that owns the dot. Before the person picks a method, it can reject with: - `invalid`: Monime won't take the order, such as one below its smallest amount. - `denied`: the dot or its Space can't take payments now, or this dot's payment sheet is already open. The open sheet carries on. - `failed`: Dash couldn't reach Monime. - `cancelled`: the person closed the sheet. - `timeout`: the sheet waited as long as Dash allows. Once they pick a method, it resolves with the payment's `status`: `completed`, `pending`, `expired`, or `cancelled` if they closed the sheet. If a method fails, the sheet stays open for them to try again. From then on, `cancel()` only stops your code waiting; the payment goes on. Read it again later with `get`. Permission in [`dot.json`](/docs/products/dash-dots/reference/dot-json): `payments`. Types: [`PaymentOptions`](/docs/products/dash-dots/reference/dash-api/payments#paymentoptions), [`PaymentCallOptions`](/docs/products/dash-dots/reference/dash-api/payments#paymentcalloptions), [`PaymentResult`](/docs/products/dash-dots/reference/dash-api/payments#paymentresult) ## `dash.payments.get` ```ts dash.payments.get(reference: string, callOptions?: CallOptions): DashRequest ``` The payment for the order with this reference, to check a pending one later or after the dot opens again. Undefined if this dot never asked for it, or the person never picked a method. Permission in [`dot.json`](/docs/products/dash-dots/reference/dot-json): `payments`. Types: [`PaymentResult`](/docs/products/dash-dots/reference/dash-api/payments#paymentresult) ## Types ### `Money` | Field | Type | What it is | | ---------- | ---------------- | ------------------------------------------------------ | | `currency` | `'SLE' \| 'USD'` | | | `value` | `number` | In minor units, as in Monime's API: SLE 75.00 is 7500. | ### `OrderLineItem` | Field | Type | What it is | | --------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | `name` | `string` | | | `unitPrice` | [`Money`](/docs/products/dash-dots/reference/dash-api/payments#money) | | | `quantity` (optional) | `number` | 1 to 100,000. Default: 1. | | `imageUrl` (optional) | `string` | An https picture Dash shows beside the item. Its host must be in `network.hosts` in `dot.json`. | ### `Order` | Field | Type | What it is | | ------------------------ | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | `string` | What the person is paying for, such as "Jazz Night tickets". 3 to 64 characters. | | `reference` | `string` | The dot's own ID for the order, up to 64 characters. The same reference never pays twice: asking again gives back the first payment. | | `description` (optional) | `string` | | | `lineItems` | [`OrderLineItem[]`](/docs/products/dash-dots/reference/dash-api/payments#orderlineitem) | 1 to 16 items, all in one currency. Dash adds them up for the total. | | `metadata` (optional) | `Record` | Up to 64 pairs, with keys up to 48 characters and values up to 100. They stay with the payment and its webhooks. Keys can't start with "@", "\_" or "monime", which Monime keeps for itself. | ### `MomoProvider` Monime's IDs for the mobile money providers: m17 is Orange Money and m18 is Africell Money. ```ts type MomoProvider = 'm17' | 'm18'; ``` ### `LinkProvider` Monime's IDs for the banks a linked account can be at. ```ts type LinkProvider = 'slb001' | 'slb004' | 'slb007' | 'slb009' | 'slb013'; ``` ### `LinkMethod` | Field | Type | What it is | | ---------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------- | | `type` | `'link'` | | | `providers` (optional) | [`LinkProvider[]`](/docs/products/dash-dots/reference/dash-api/payments#linkprovider) | The only banks that can pay. Empty or left out means any. | ### `CardMethod` | Field | Type | What it is | | ------ | -------- | ---------- | | `type` | `'card'` | | ### `MomoMethod` | Field | Type | What it is | | ------------------------ | ------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | `type` | `'momo'` | | | `providers` (optional) | [`MomoProvider[]`](/docs/products/dash-dots/reference/dash-api/payments#momoprovider) | The only providers that can pay. Empty or left out means both. | | `phoneNumber` (optional) | `string` | Only this number can pay, such as "+23276123456". | ### `PaymentMethod` ```ts type PaymentMethod = LinkMethod | CardMethod | MomoMethod; ``` Types: [`LinkMethod`](/docs/products/dash-dots/reference/dash-api/payments#linkmethod), [`CardMethod`](/docs/products/dash-dots/reference/dash-api/payments#cardmethod), [`MomoMethod`](/docs/products/dash-dots/reference/dash-api/payments#momomethod) ### `PaymentOptions` | Field | Type | What it is | | ------------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `order` | [`Order`](/docs/products/dash-dots/reference/dash-api/payments#order) | | | `methods` (optional) | [`PaymentMethod[]`](/docs/products/dash-dots/reference/dash-api/payments#paymentmethod) | The methods to offer, in order, each with its own settings. Leave it out for all three with no limits. | | `financialAccountId` (optional) | `string` | The financial account the money goes to, such as "fac-k6VgVTfSmLruHpiQgMg4DUeySZx". It must belong to the Space that owns the dot and hold the order's currency. Leave it out for the Space's main account. | ### `PaymentStatus` `failed` comes only from `get`, for a pending payment that failed later. ```ts type PaymentStatus = 'pending' | 'completed' | 'failed' | 'expired' | 'cancelled'; ``` ### `CardPaymentResult` Also has the fields of [`PaymentResultBase`](/docs/products/dash-dots/reference/dash-api/payments#paymentresultbase). | Field | Type | What it is | | ------------------- | -------- | -------------------------------------------------- | | `method` | `'card'` | | | `checkoutSessionId` | `string` | The Monime checkout session the card paid through. | ### `MomoPaymentResult` Also has the fields of [`PaymentResultBase`](/docs/products/dash-dots/reference/dash-api/payments#paymentresultbase). | Field | Type | What it is | | --------------- | -------- | ------------------------------------------------------ | | `method` | `'momo'` | | | `paymentCodeId` | `string` | The Monime payment code the mobile money paid through. | ### `LinkPaymentResult` Also has the fields of [`PaymentResultBase`](/docs/products/dash-dots/reference/dash-api/payments#paymentresultbase). | Field | Type | What it is | | ----------- | -------- | ------------------------------------------- | | `method` | `'link'` | | | `paymentId` | `string` | The Monime payment the linked account made. | ### `PaymentResult` ```ts type PaymentResult = CardPaymentResult | MomoPaymentResult | LinkPaymentResult; ``` Types: [`CardPaymentResult`](/docs/products/dash-dots/reference/dash-api/payments#cardpaymentresult), [`MomoPaymentResult`](/docs/products/dash-dots/reference/dash-api/payments#momopaymentresult), [`LinkPaymentResult`](/docs/products/dash-dots/reference/dash-api/payments#linkpaymentresult) ### `PaymentCallOptions` No `timeout`: Dash decides how long the sheet waits. ```ts type PaymentCallOptions = Omit; ``` Types: [`CallOptions`](/docs/products/dash-dots/reference/dash-api#calls) ### `PaymentResultBase` | Field | Type | What it is | | ------------------------ | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `reference` | `string` | The order's `reference`. | | `requestId` | `string` | Dash's ID for the payment request. Give it to Monime's support when asking about a payment. | | `status` | [`PaymentStatus`](/docs/products/dash-dots/reference/dash-api/payments#paymentstatus) | How the payment stands now. | | `amount` | [`Money`](/docs/products/dash-dots/reference/dash-api/payments#money) | The order's total. | | `paymentId` (optional) | `string` | Monime's payment, such as "pay-…", once there is one. | | `orderNumber` (optional) | `string` | Monime's number for the order, for the person's receipt and for support. Only once the payment has completed. |