diff --git a/docs.json b/docs.json index 30e3f23..e413302 100644 --- a/docs.json +++ b/docs.json @@ -20,6 +20,9 @@ "source": "https://brand-assets.runa.io/design-system/fonts/f37lineca/F37Lineca-Bold.woff2" } }, + "styling": { + "eyebrows": "breadcrumbs" + }, "navigation": { "tabs": [ { @@ -61,7 +64,16 @@ "features/limiting-available-products", "features/user-redemption-templates", "features/merchant-selection-template", - "features/embedded-fx" + "features/embedded-fx", + { + "group": "Pay to Card", + "icon": "boxes-stacked", + "pages": [ + "features/pay-to-card/introduction", + "features/pay-to-card/testing", + "features/pay-to-card/support" + ] + } ] }, { diff --git a/features/pay-to-card.mdx b/features/pay-to-card.mdx deleted file mode 100644 index 804207a..0000000 --- a/features/pay-to-card.mdx +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: "Pay to Card" -description: "Provide faster access to funds for your recipients by pushing funds to cards." -icon: "credit-card" ---- - -Powered by Visa Direct and Mastercard Send, Runa Pay to Card is the fastest and simplest way to send funds directly to your recipients' bank account. - -Pay to Card facilitates instant transfers to other accounts, powering use cases like gig worker payments, rewards, incentives insurance claims, corporate rebates, payroll, government aid, and reimbursements. - -Sending payouts with Runa is simple and straightforward. If you already have a Runa account, you can skip straight to sending your first payment. If you are new to Runa, you will need to [create an account to get started](https://app.runa.io/signup). - -Before you go live with Runa Pay to Card you will need to sign updated T&Cs. Please reach out to your Account Manager or email [support@runa.io](mailto:support@runa.io) to complete this step. - -## 1️⃣ Getting started - -- Ensure you have [created an API key](/getting-started/api-key). -- Ensure you have funded your account with the required balance to cover the payments you intend to make. You can use the [balances endpoint](/features/balances) to check your account balance. -- Retrieve the Pay to Card products using the [product list endpoint](/reference/2024-02-05/endpoint/products/list). You can identify these products by the `payout_type` field, which will be set to `payment`. Each Pay to Card product supports a specific currency and country. You can refer to the [product listing guide](/features/product-catalog) for more information on this endpoint. -- Familiarise yourself with the [ordering endpoint](/getting-started/first-order/sync). To make an order for a payment you simply specify the Pay to Card product code for the currency and country you wish to send funds in. -- Place an order for a pay to card payment. You can opt for us to send the payment to the recipient's email address by using the `EMAIL` distribution method or you can send the payment link to the recipient yourself by using the `LINK` method. - -### Example pay to card order - -The following is an example of a pay to card order for a $10 payment to a recipient in the US. The payment will be sent to the recipient's email address. - -```http -POST https://api.runa.io/v2/order -Content-Type: application/json -X-Api-Key: - -{ - "payment_method": { - "type": "ACCOUNT_BALANCE", - "currency": "USD" - }, - "items": [ - { - "face_value": 10, - "distribution_method": { - "type": "EMAIL", - "email_address": "" - }, - "products": { - "type": "SINGLE", - "values": ["P2C-US"] - } - } - ] -} -``` - -Refer to the [order endpoint reference](/reference/2024-02-05/endpoint/orders/create) for more information on the request schema and other options available. - -## 💳 Pay to Card redemption experience - - - - -When a recipient opens the payment they will be guided through the following flow on their first redemption: - -1. Enter their email address to authenticate -2. Securely enter their card details -3. Receive funds in their bank account - -For a returning recipient, they will only need to enter their email address to authenticate. The previously used card details are saved for future redemptions. - -## 🛟 Support - -We've categorized potential errors into three distinct areas, and for each, we've developed specific contingency plans and operational procedures. - -### 👤 User errors - -These are errors that can be self-corrected by recipients - -#### Payment details - -1. Issue with the card number - - User will see the error message: The card number you have entered is incorrect. -2. Card is unsupported - - User will see the error message: The card you have entered is not supported. Please use a Visa or Mastercard debit card. - -#### Returning user - -1. Returning user lands on the first page but has already redeemed the balance. - - User will see the error message: You have already redeemed the balance. - -### 🖥️ Order errors - -These are faults that will require your input to resolve - -#### Insufficient funds - -1. Insufficient balance at order time - - If your account has insufficient balance you will be unable to create the order for the payment. The API response with a 400 status code, the error message body will contain the type `insufficient_funds`. Check the [order endpoint reference](/reference/2024-02-05/endpoint/orders/create) for more information. - -#### User ineligible - -1. Payments cannot be sent to anyone under 18 years old. - - User will see the error message: We cannot send funds to anyone under the age of 18. -2. Payments cannot be sent to anyone who appears on a sanctions list. - - User will see the error message: There's been an unexpected issue, please contact the issuer of this link. - - Runa will send you an email to inform you that this has happened, with our reasoning attached. -3. Card issue - - Payment sent to a user who doesn't have an eligible debit card with Visa/Mastercard. - - User will see the error message: We can only send funds to a Visa or Mastercard debit card. - -### ⚙ Processing errors - -#### In-journey errors - -1. Authentication error: Recipient hasn't received email with code - - User will need to contact Runa for us to investigate what might have gone wrong with authentication. -2. Authentication error: Code that recipient has received not working. - - User will need to contact Runa for us to investigate what might have gone wrong with authentication. -3. Card issue: The recipient's saved card has expired. - - User will see the error message: "Card expired" and will be able to contact Runa for us to delete their original card so they can add a new one. - - _Note: from early April recipients will be able to self-serve editing their existing cards_ -4. Card issue: The recipient's saved card has expired. - - User will see the error message: "Card expired" and will be able to contact Runa for us to delete their original card so they can add a new one. - - _Note: from early April recipients will be able to self-serve editing their existing cards_ -5. Fraud Suspected - - If fraud is suspected, we will hold on sending out the payout until we have established that the payment isn't fraudulent. During this time, we will either ask the end recipient to share additional information, or we will have to cancel the payment and inform you that it's been cancelled with a reason as to why. -6. Recipient bank has rejected payment - - The most common payment issue we are likely to experience is the recipient's bank rejecting the payment we send them. If this happens we will send the recipient an email to say their bank has rejected the payment, with advice to either resolve this with their bank or to contact us to manually delete their card so they can try a different card. - -### All other issues - -Your point of contact for any other issues: support@runa.io diff --git a/features/pay-to-card/introduction.mdx b/features/pay-to-card/introduction.mdx new file mode 100644 index 0000000..7e7fbf6 --- /dev/null +++ b/features/pay-to-card/introduction.mdx @@ -0,0 +1,96 @@ +--- +title: "Using Pay to Card" +description: "Provide faster access to funds for your recipients by pushing funds to cards." +icon: "credit-card" +--- + +Powered by Visa Direct and Mastercard Send, Runa Pay to Card is the fastest and simplest way to send funds directly to your recipients' bank account. + +Pay to Card facilitates instant transfers to other accounts, powering use cases like gig worker payments, rewards, incentives, insurance claims, corporate rebates, payroll, government aid, and reimbursements. + + + To get access to Pay to Card, please reach out to your Account Manager or + email support@runa.io. + + +## Fetching the Pay to Card products + +Retrieve the Pay to Card products using the [product list endpoint](/reference/2024-02-05/endpoint/products/list). You can identify these products by the `payout_type` field, which will be set to `payment`. Each Pay to Card product supports a specific currency and country. You can refer to the [product listing guide](/features/product-catalog) for more information on this endpoint. + +```json title="Pay to Card product example, fields truncated for brevity" icon="file" expandable +{ + "code": "P2C-US", + "name": "Pay To Card US", + "currency": "USD", + "state": "LIVE", + "payout_type": "payment", + "is_orderable": true, + "availability": "realtime" +} +``` + +## Placing a Pay to Card order + +To make an order for a payment you simply specify the Pay to Card product code for the currency and country you wish to send funds in. + +For our example, we will be using the `P2C-US` product code for a $10 payment to a recipient. The payment will be sent to the recipient's email address via the `EMAIL` distribution method. + +```http title="Example pay to card order" icon="globe" expandable +POST https://api.runa.io/v2/order +Content-Type: application/json +X-Api-Key: + +{ + "payment_method": { + "type": "ACCOUNT_BALANCE", + "currency": "USD" + }, + "items": [ + { + "face_value": 10, + "distribution_method": { + "type": "EMAIL", + "email_address": "" + }, + "products": { + "type": "SINGLE", + "values": ["P2C-US"] + } + } + ] +} +``` + +### Distribution methods + +In the example above we used the `EMAIL` distribution method to send the payment to the recipient's email address. + +- You can also use the `RECIPIENT` distribution method to send the payment to a known recipient. +- If you want to handle the distribution of the payment link yourself, use the `PAYOUT_LINK` distribution method. + +Refer to the [order endpoint reference](/reference/2024-02-05/endpoint/orders/create) for more information on the request schema and other options available. + +## Recipient redemption experience + + + + +When a recipient opens the payment link, they will be guided through the following flow on their first redemption: + +1. Enter their email address to authenticate +2. Securely enter their card details +3. Receive funds in their bank account + +For a returning recipient, they will only need to enter their email address to authenticate. The previously used card details are saved for future redemptions. + +## Next steps + + + + Test out the pay to card redemption journey in our playground environment. + + + Read through the potential failure scenarios and suggested resolution for + each. + + diff --git a/features/pay-to-card/support.mdx b/features/pay-to-card/support.mdx new file mode 100644 index 0000000..db728db --- /dev/null +++ b/features/pay-to-card/support.mdx @@ -0,0 +1,51 @@ +--- +title: "Support" +description: "Potential error scenarios for Pay to Card and their resolution." +icon: "circle-info" +--- + +We've categorized potential errors into three distinct areas, and for each, we've developed specific contingency plans and operational procedures. + +## Recipient errors + +These are errors that can be self-corrected by your recipients. + +### Payment details + +1. Issue with the card number + - Recipient will see the error message: `The card number you have entered is incorrect.` +2. Card is unsupported + - Recipient will see the error message: `The card you have entered is not supported. Please use a Visa or Mastercard debit card.` + + +## Order errors + +These are the errors that will require your input to resolve + +### Recipient ineligible + +1. Payments cannot be sent to anyone under 18 years old. + - Recipient will see the error message: `We cannot send funds to anyone under the age of 18.` +2. Payments cannot be sent to anyone who appears on a sanctions list. + - Recipient will see the error message: `There's been an unexpected issue, please contact the issuer of this link.` + - Runa will send you an email to inform you that this has happened, with our reasoning attached. +3. Card issue + - Payment sent to a recipient who doesn't have an eligible debit card with Visa/Mastercard. + - Recipient will see the error message: `We can only send funds to a Visa or Mastercard debit card.` + +In these cases, we recommend cancelling the payout link by logging into your Runa portal. Please use an alternate payout mechanism to transfer the funds to your recipient. + +## Processing errors + +### In-journey errors + +1. Authentication error: Recipient hasn't received email with code, or the code is not working + - Recipient will need to contact Runa for us to investigate what might have gone wrong with authentication. +2. Fraud Suspected + - If fraud is suspected, we will hold on sending out the payout until we have established that the payment is genuine. During this time, we will either ask the end recipient to share additional information, or we will have to cancel the payment and inform you that it's been cancelled with a reason as to why. +3. Recipient bank has rejected payment + - The most common payment issue we are likely to experience is the recipient's bank rejecting the payment we send them. If this happens, we will send the recipient an email to say their bank has rejected the payment, with advice to either resolve this with their bank or try a different card. + +## All other issues + +Your point of contact for any other issues: support@runa.io diff --git a/features/pay-to-card/testing.mdx b/features/pay-to-card/testing.mdx new file mode 100644 index 0000000..c709872 --- /dev/null +++ b/features/pay-to-card/testing.mdx @@ -0,0 +1,81 @@ +--- +title: "Testing" +description: "Steps to simulate different pay to card redemption scenarios in playground." +icon: "flask" +--- + +The Pay to Card redemption journey requires a few steps from the recipient. To test this journey in the playground environment, you can use the following steps. + + + For testing and simulating errors during placing of the order, refer to the + [playground reference section](/docs/playground). + + +Here's a high level summary of the Pay to Card redemption journey: + + + + +You're able to walk through each step of the journey in the playground environment. + + + **Email delivery of links for orders is disabled in the playground environment by + default** + + Every order via API will always return a link in the `payout.url` field + that you can use to access the redemption journey. See the [playground + reference](/docs/playground) for more information. + + +## Testing the redemption journey + +After placing the order, you can access the redemption journey by following the link in the `payout.url` field of the API response. + +### Email verification + +Playground supports email verification via one time code, just like our live environment. + +You can test both successful and error cases by trying scenarios such as: + +1. Correct email and code. +2. Incorrect code. + +### Billing address and card details + + + Never enter your real address or card details on playground links. + + +There is no billing address validation in the Playground environment, so you can use any dummy address. + +The playground environment only works with a specific set of cards. Use the following cards to trigger different scenarios. + +1. Valid card details + + Use the following details to trigger a success response: + + Card Number: `4111 1111 1111 1111` + + CVV, Expiry Date, and Cardholder name: any values + +2. Card details for validation error + + Any incorrect card should immediately trigger an error (example below): + + Card Number: `4111 1111 1111 1112` + + CVV, Expiry Date, and Cardholder name: any values + +### The returning recipient case + +A returning recipient will already have their card and other details saved. + +To simulate a returning recipient experience in the Playground environment, append `+repeat` to the username part of your email address. + +For example, if your email is `user@example.com`, use `user+repeat@example.com`. + +You will still receive the one-time code in your usual inbox. + +### Support + +If you face any issues while testing, feel free to contact your account manager or Runa support at: support@runa.io diff --git a/reference/2024-02-05/playground.mdx b/reference/2024-02-05/playground.mdx index 642e6a2..52b1dcf 100644 --- a/reference/2024-02-05/playground.mdx +++ b/reference/2024-02-05/playground.mdx @@ -138,6 +138,10 @@ Some errors cannot be triggered in playground through incorrect formatting or re | `insufficient_funds` | The account balance you're trying to use to pay for your order does not have enough funds. | | `internal_server_error` | An unknown error occurred in our services. | +## Redemption experience + +You should be able to test the basic redemption experience for most product types in the Playground. While we can’t guarantee a like-for-like match with the production redemption experience—due to inherent limitations in testing financial products—we make our best effort to keep the experience as consistent as possible. + ## Continuous improvement We are continuously enhancing the Playground environment to better serve your needs for experimenting and testing integrations. Expect ongoing improvements and more features to be added over time.