SPEI integration guide
SPEI through Openpay is a payment provider allowing customers to pay using payment methods saved to their SPEI account. This section is intended to help you implement SPEI based on your preferred integration workflow.
Services and compatibility
Payment method gateway name | Openpay |
Supported transaction types | |
Supported integration methods |
|
Supported processing currencies | MXN |
Webhook event types |
|
Gateway-specific information
Work with Integrations Support to configure your Openpay gateway credentials in Nexio for the Extract-Transform-Load (ETL) process, which is important for keeping the transaction statuses in sync with Openpay.
The source ID (Openpay token) is auto-assigned through Nexio. This is only supported if the TokenEx account is owned by Nexio.
Configuring and utilizing webhooks is necessary as part of the SPEI workflow. For information about webhooks, see Webhooks and event types.
The following are not supported with Openpay:
- Kount
Configuration
Apart from working with Integrations to add SPEI as a payment method, you do not need to do any other configuration steps.
Required fields
The following table shows the required and conditional fields for SPEI transactions in the Create APM one-time-use token request.
Field | Required? | Description |
---|---|---|
data.amount | Yes | The transaction amount. |
data.currency | Yes | The three-character ISO currency code for the transaction. SPEI only supports MXN for the processing currency, |
data.customer.orderNumber | Yes | The order number. |
data.customer.firstName | Yes | The customer's first name, as it is set for the payment method. |
data.customer.lastName | Yes | The customer's last name, as it is set for the payment method. |
data.customer.email | Yes | The customer's email address. |
customerRedirectUrl | No | The URL to which the customer will be redirected after completing their payment. The customer will be sent here upon successful or failed payment. This URL must use the HTTPS protocol. |
data.cart.items[n].item | No | Item number or code. |
data.cart.items[n].description | No | A description of the item. |
data.cart.items[n].quantity | No | The quantity sold. |
data.cart.items[n].price | No | The price per item. |
data.customer.billToAddressOne | No | The street address for the customer. |
data.customer.billToAddressTwo | No | Additional street address information, if required. |
data.customer.billToCity | No | The city for the address record. |
data.customer.billToState | No | The state or province on file with the payment provider. (If in the US, this must be the two-character state abbreviation). |
data.customer.billToPostal | No | The postal code on file. |
data.customer.billToCountry | No | The two-character (Alpha-2) ISO country code. |
data.customer.billToPhone | No | The billing phone number. |
data.customer.birthDate | No | The customer's date of birth. For specific details related to this parameter, see the Create APM one-time-use token endpoint. This parameter only applies for the Paynet and SPEI alternative payment methods. |
data.customer.customerRef | No | Customer identifier. You can use this field to pass a customer ID to the APM or to manage user subscriptions. |
data.customer.invoice | No | The invoice number. |
data.customer.shipToAddressOne | No | The shipping address, if different from the billing address. |
data.customer.shipToAddressTwo | No | Additional shipping address information, if required. |
data.customer.shipToCity | No | The shipping city. |
data.customer.shipToState | No | The shipping state or province. (If in the US, this must be the two-character state abbreviation). |
data.customer.shipToPostal | No | The shipping postal code. |
data.customer.shipToCountry | No | The two-character (Alpha-2) ISO shipping country code. |
data.customer.shipToPhone | No | The shipping phone number. |
data.customFields | No | Nexio stores information in custom fields and passes custom fields to the gateway. |
data.description | No | A description of the transaction. |
data.descriptor | No | Include this parameter to dynamically change the descriptor on the customer's statement. |
data.dueDate | No | The date by which the customer must complete the payment, sent in ISO-8601 format. If the transaction is not settled before this date, it will be voided. If you do not provide a value, the system automatically sets the date to be 30 days from the current date. This parameter only applies for the Paynet and SPEI alternative payment methods. |
data.paymentMethod | No | The identifier for the alternative payment method. Use this parameter when you want to only return the SPEI iframe button URL or the SPEI redirect URL (rather than data for all payment methods associated with the account). The value to use is openpaySpei . |
data.totalTaxAmount | No | Total tax amount. |
processingOptions.merchantId | No | The Nexio merchant ID (MID). |
processingOptions.paymentOptionTag | No | A custom value used to route transactions to a specific gateway or merchant account. |
uiOptions.displaySubmitButton | No | Set to true to include a submit button in the iframe. |
uiOptions.css | No | The URL where your custom CSS file is hosted. |
Example requests
The following is an example one-time-use token request for SPEI.
curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic [Base64_encoded_login]'
-d '{
"data": {
"amount": 4.00,
"currency": "MXN",
"paymentMethod": "openpaySpei",
"customer": {
"orderNumber": "12345678",
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]"
}
}
}'
A successful request returns a response similar to the following:
{
"expiration": "2018-09-18T15:43:05.664Z",
"token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
"scriptUrl": "https://api.nexiopaysandbox.com/apm/v3/script?token=b61ca2a9-b804-4a28-a00e-b794c8975dee",
"expressIFrameUrl": "https://www.api.nexiopaysandbox.com/v3?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2",
"redirectUrls": [...],
"buttonIFrameUrls": [
{
"paymentMethod": "openpaySpei",
"url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=openpaySpei"
},
{
"paymentMethod": "payPal",
"url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=payPal"
}
]
}
For the multi iframe integration method: You use the expressIFrameUrl
value in the steps for the transaction.
For the individual iframe option: You use the buttonIFrameUrls.url
of the openpaySpei
APM for the transaction.
For the custom redirect option: You use the redirectUrls.url
of the openpaySpei
APM for the transaction.
Transaction types and integration methods
Regardless of the integration method workflow you implement, consumers are redirected to SPEI to complete their transactions.
Nexio supports the following transaction types for SPEI:
- Sale
-
- In an iframe that displays all payment methods available to the customer (based on the customer’s location and the merchant’s configured payment methods)
- In an individual iframe
- Using your own button or image
A page similar to the following displays when a user clicks the SPEI payment option. It contains instructions (in the user's default browser language) for how to use the voucher.

Testing data
For testing data, see Openpay's Pruebas [Tests] page.
Response handling
In the one-time-use token request, SPEI gets returned in the paymentMethod
parameter as openpaySpei
.
Nexio responds with transaction results in one of the following ways, depending on your integration workflow:
- Event messages: This applies to integrations that do not pass a
customerRedirectUrl
in the request. - Response fields in the URL: This applies to integrations that do provide a
customerRedirectUrl
in the request.
In addition to one of the above, if your merchant account is configured to receive webhooks, Nexio provides responses to the webhook URLs that have been registered. For further explanation of the webhook event types, see the webhook Event types table.
For SPEI, these are the possible webhook event types:
- TRANSACTION_PENDING
- TRANSACTION_SETTLED
For information about how to run each of the integration workflows, see Transaction types and integration methods above.
Status workflows
The status of a successful transaction with SPEI varies, depending on the options you choose.
Sale | Successful sale transactions have the following statuses:
|
*Pending status displays as "authorized" or "AUTHORIZED" in the Nexio Dashboard; it displays as 10
, meaning "authorized", in the response when querying transactions (for more information about transactionStatus
, see the table).
Next steps
Now, you are ready to get started with running transactions:
If you have any additional questions or feedback, see Contact us.
Updated 8 days ago