Quickstart (OLD)
Try the Payment Initiation API in less than 10 minutes
To start using Fintoc's Payment Initiation API, you just need to create an account on our Dashboard and follow these five steps:
- Get your test API Keys
- Create a Payment Intent
- Open the Widget
- Handle post-payments events
- Make your first payment
Step 1: Get your test API Keys
Every interaction with the Fintoc API must be authenticated with the API Keys of your Fintoc account. If an interaction with the API does not include your API Key or includes an incorrect API Key, Fintoc will return an error.
Every Fintoc account has two key pairs: one corresponds to the test mode, while the other corresponds to the actual API environment. Every resource is stored either in test mode or in live mode, and resources from one environment cannot be manipulated by resources from the other environment.
Your API Keys will be available in the Dashboard. First you need to create an account on the Fintoc Dashboard. Once your Fintoc account has been created, you will be able to get your API Keys. In this case, you must use the Public Key and Secret Key from test mode. To easily identify them, we added the prefix pk_test_ and sk_test_, respectively.
Step 2: Create a Payment Intent
Using your test Secret Key, create a Payment Intent from your backend with the amount and currency of the payment. Always create the Payment Intent from your backend, or a malicious user could alter any of those fields.
If you plan on using the Refunds product, you must include a customer_email
in the Payment Intent request.
Here's an example of creating a Payment Intent for Chile:
curl --request POST "https://api.fintoc.com/v1/payment_intents" \
-- header 'Authorization: YOUR_SECRET_API_KEY' \
-- header 'Content-Type: application/json' \
--data-raw '{
"amount": 2476,
"currency": "CLP",
"customer_email":"[email protected]"
}'
const fetch = require('node-fetch');
const payment_intent = {
amount: 1000,
currency: 'clp',
customer_email:'[email protected]'
}
fetch('https://api.fintoc.com/v1/payment_intents', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'YOUR_SECRET_API_KEY'
},
body: JSON.stringify(payment_intent),
},
)
import requests
payment_intent = {
'amount': 1000,
'currency': 'clp',
'customer_email':'[email protected]'
}
headers = {
'Accept': 'application/json', 'Authorization': 'YOUR_SECRET_API_KEY'
}
r = requests.post(
'https://api.fintoc.com/v1/payment_intents',
json=payment_intent,
headers=headers
)
require 'net/http'
require 'uri'
require 'json'
payment_intent = {
amount: 1000,
currency: 'clp',
customer_email: '[email protected]'
}
uri = URI("https://api.fintoc.com/v1/payment_intents")
header = {
Accept: 'application/json', Authorization: 'YOUR_SECRET_API_KEY'
}
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri.request_uri, header)
request.body = payment_intent.to_json
response = http.request(request)
If you want to create a Payment Intent for Mexico, change the currency to MXN
.
Currencies are represented as integers
The Fintoc API represents currencies in its smallest possible units with no decimals (as an integer). That means that an amount of MXN 10.29 gets represented by Fintoc as 1029. You can read more about currencies here.
The response should look like this:
{
"id": "pi_BO381oEATXonG6bj",
"object": "payment_intent",
"amount": 1000,
"currency": "CLP",
"widget_token": "pi_BO381oEATXonG6bj_sec_a4xK32BanKWYn",
"status": "created",
"metadata": {},
"reference_id": null,
"recipient_account": {
"holder_id": "183917137",
"number": "123456",
"type": "checking_account",
"institution_id": "cl_banco_de_chile"
},
"sender_account": null,
"created_at": "2021-10-15T15:23:11.474Z",
}
Step 3: Open the Widget
Your new created PaymentIntent
should contain the widget_token
attribute. You must use that attribute and your test Public Key to set up the widget and the user's workflow.
The widget token is temporary
The
widget_token
is temporary and will expire 10 minutes after its creation.
Here's an example of how you can open the widget with your Public Key andwidget_token
configured for a Chilean payment:
<!DOCTYPE html>
<html lang="en">
<head>
<meta name="viewport" content="width=device-width,initial-scale=1.0, maximum-scale=1.0">
<title>Fintoc Demo</title>
<script src="https://js.fintoc.com/v1/"></script>
</head>
<body>
<script>
window.onload = () => {
const widget = Fintoc.create({
holderType: 'individual',
widgetToken: 'pi_XXXXXXXX_sec_YYYYYYYY',
product: 'payments',
country: 'cl',
publicKey: 'YOUR_PUBLIC_KEY',
onSuccess: () => {},
});
widget.open();
};
</script>
</body>
</html>
You should only use holderType
as individual
since our Payment Initiation API is designed for individual
accounts.
If you want a Mexican payment, change the country parameter to mx
.
To learn more about the Widget, its integration, and how to listen to Widget events, take a look to the Widget guide.
Use the Widget callbacks and events correctly
Never use the
onSuccess
,onExit
oronEvent
callbacks to get the state of the Payment Intent being created. You should only use these callbacks to handle the flow of your frontend application, while waiting backend confirmation via Webhooks. Frontend events can also be used to generate metrics about general widget usage, but you should never rely solely on them to assume a Payment Intent was created or failed to be created.
Step 4: Handle post-payment events
Fintoc sends a payment_intent.succeeded
event when the payment completes. Use the webhook guide to receive these events and run actions, such as sending an order confirmation email to your customer, logging the sale in a database, or starting a shipping workflow.
Listen for these events rather than waiting on a callback from the client. From the client side, On the client, the customer could close the browser window or quit the app before the callback executes, and malicious clients could manipulate the response.
We recommend handling the following events:
Event | Description | Action |
---|---|---|
payment_intent.succeeded | Sent when a customer has successfully completed a payment. | Send the customer an order confirmation and fulfill their order. |
payment_intent.failed | Sent when a customer attempted a payment, but the payment failed. | Offer the customer another attempt to pay. |
payment_intent.rejected | Sent when the user rejects the payment. This may happen when the user rejects the MFA or enters it incorrectly. | Offer the customer another attempt to pay. |
payment_intent.pending | Sent when the payment order was executed but the final status of the payment is not available yet. This only happens in rare occasions when the bank is not able to provide a definite status. A future webhook event will be sent once it's determined. It can take up to 10 days for some payments to move from pending to failed or succeeded. | Inform the customer that you've received their order and are awaiting the final status of the payment to fulfill. |
Learn more about webhooks
To learn more about how to create your own webhook endpoint, test your webhook endpoint and security best practices read our Webhooks guide.
Step 5: Make your first payment
Once the widget appears on your screen, follow the payment flow using Fintoc's test special values. For a successful payment, you can use one of these values:
- In Chile, select any bank and login using the
41614850-3
rut andjonsnow
password. Once you are logged in to the bank, select the account with the number422159212
. After you select that account, wait 5 seconds and the payment should be successful. - For Mexico, select any bank and write the number
5555555555
. Wait 5 seconds and the payment should be successful.
You should have received a payment_intent.succeeded
event in your webhook endpoint.
Congratulations! You just made your first Fintoc payment! To test different payment flows, see Fintoc's test special values.
Updated 18 days ago