Niubiz Gateway Guide

Niubiz fact sheet

Quick Start

New to integrating Niubiz with Spreedly? Here's your setup guide:

Retrieve your Niubiz credentials
1. Log into your Niubiz merchant portal.
2. Request your API integration credentials from Niubiz (the same user/password used to obtain a security access token).
3. Collect your username, password, and merchant id (merchantId / código de comercio).
4. Niubiz uses a two-step authentication flow. Spreedly first calls the Security API (GET /api.security/v1/security) using HTTP Basic auth (username:password) to obtain a short-lived access token (valid ~59 minutes). That access token is then sent in the Authorization header on every subsequent transaction request. Spreedly caches and refreshes the access token automatically.
Get familiar with the Spreedly API
1. Review Spreedly API basics
2. Understand the core concepts: Gateways, Payment Methods, and Transactions
Add Niubiz gateway to Spreedly in sandbox mode

📘
Review this documentation to understand more about how to test transactions.

Additional notes

Additional notes
Merchant ID is required. It can be stored on the gateway credentials or passed per-transaction via the `merchant_id` gateway specific field. If missing, the transaction fails with `merchant_id_missing`. All authorize/purchase/verify/capture transactions are sent with `captureType = manual.` `authorize` sends `accountable = false`; `purchase` sends `accountable = true.` Void annuls the original authorization or purchase using its `signature` (`PUT /api.authorization/v3/void/ecommerce/{merchantId}/{signature}).` An `annulation_reason` gateway specific field may be supplied. Refund (credit) is a full refund only; partial refund is not supported. A `ruc` and `description/comment` may be supplied. Verify performs a 0-amount validation via the Validate API and can optionally tokenize the card (`tokenize` GSF). Apple Pay and Google Pay are supported via network tokenization (the cryptogram is sent as `tavv` with `eci` = `07`). Currency defaults to `USD`; amounts are sent in the gateway's decimal format.

Merchant ID is required. It can be stored on the gateway credentials or passed per-transaction via the merchant_id gateway specific field. If missing, the transaction fails with merchant_id_missing.

All authorize/purchase/verify/capture transactions are sent with captureType = manual.

authorize sends accountable = false; purchase sends accountable = true.

Void annuls the original authorization or purchase using its signature (PUT /api.authorization/v3/void/ecommerce/{merchantId}/{signature}). An annulation_reason gateway specific field may be supplied.

Refund (credit) is a full refund only; partial refund is not supported. A ruc and description/comment may be supplied.

Verify performs a 0-amount validation via the Validate API and can optionally tokenize the card (tokenize GSF).

Apple Pay and Google Pay are supported via network tokenization (the cryptogram is sent as tavv with eci = 07).

Currency defaults to USD; amounts are sent in the gateway's decimal format.

Adding a Niubiz Gateway

Required Credentials

username: Niubiz integration username (used for the Security API basic auth).
password: Niubiz integration password (used for the Security API basic auth).

Required (credential or gateway specific field)

merchant_id: Your Niubiz merchant identifier. Store it on the gateway or pass it per-transaction via the merchant_id gateway specific field.

REQUEST

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
  <gateway_type>niubiz</gateway_type>
  <username>your_username</username>
  <password>your_password</password>
  <merchant_id>your_merchant_id</merchant_id>
</gateway>'

RESPONSE

<gateway>
    <token>XXXXXXXXXXXXXXXXXXXXXXXXXX</token>
    <gateway_type>niubiz</gateway_type>
    <name>Niubiz</name>
    <description nil="true"/>
    <merchant_id>your_merchant_id</merchant_id>
    <characteristics>
        <supports_purchase type="boolean">true</supports_purchase>
        <supports_authorize type="boolean">true</supports_authorize>
        <supports_capture type="boolean">true</supports_capture>
        <supports_partial_capture type="boolean">false</supports_partial_capture>
        <supports_credit type="boolean">true</supports_credit>
        <supports_partial_credit type="boolean">false</supports_partial_credit>
        <supports_void type="boolean">true</supports_void>
        <supports_verify type="boolean">true</supports_verify>
        <supports_3dsecure_2_mpi_purchase type="boolean">true</supports_3dsecure_2_mpi_purchase>
        <supports_3dsecure_2_mpi_authorize type="boolean">true</supports_3dsecure_2_mpi_authorize>
        <supports_network_tokenization type="boolean">true</supports_network_tokenization>
        <supports_stored_credentials type="boolean">true</supports_stored_credentials>
    </characteristics>
    <credentials>
        <credential>
            <name>username</name>
            <value>your_username</value>
        </credential>
        <credential>
            <name>merchant_id</name>
            <value>your_merchant_id</value>
        </credential>
    </credentials>
    <gateway_specific_fields>
        <gateway_specific_field>channel</gateway_specific_field>
        <gateway_specific_field>merchant_id</gateway_specific_field>
        <gateway_specific_field>external_transaction_id</gateway_specific_field>
        <gateway_specific_field>tokenize</gateway_specific_field>
        <gateway_specific_field>ruc</gateway_specific_field>
        <gateway_specific_field>annulation_reason</gateway_specific_field>
    </gateway_specific_fields>
    <payment_methods>
        <payment_method>credit_card</payment_method>
    </payment_methods>
    <state>retained</state>
    <redacted type="boolean">false</redacted>
    <sandbox type="boolean">true</sandbox>
</gateway>

PURCHASE

curl https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.json \
-u 'EnvironmentKey:AccessSecret' \
-H "Content-Type: application/json" \
-d '{
  "transaction": {
    "payment_method_token": "payment_method_token",
    "amount": 100,
    "currency_code": "USD",
    "order_id": "12345678901",
    "retain_on_success": true,
    "gateway_specific_fields": {
      "niubiz": {
        "channel": "pasarela",
        "merchant_id": "456879853"
      }
    }
  }
}'

📘
Note
order_id is mapped to Niubiz's purchaseNumber (Número de Pedido, unique per authorization attempt, max 12). If it is not supplied, Spreedly generates a numeric purchase number.

Gateway Specific Fields

<gateway_specific_fields>
  <niubiz>
    <gateway_specific_field>channel</gateway_specific_field>
    <gateway_specific_field>merchant_id</gateway_specific_field>
    <gateway_specific_field>external_transaction_id</gateway_specific_field>
    <gateway_specific_field>tokenize</gateway_specific_field>
    <gateway_specific_field>ruc</gateway_specific_field>
    <gateway_specific_field>annulation_reason</gateway_specific_field>
  </niubiz>
</gateway_specific_fields>

Descriptions and example values below use Niubiz's official field documentation where available. The Niubiz field name each maps to is shown in parentheses.

Field Name	Type	Required	Applies To	Description	Example Value
merchant_id	String	Yes (if not on gateway)	All	Niubiz merchant code created at the time of affiliation (`merchantId`), length 9.	456879853
channel	String	No (Niubiz marks it required)	All	Channel where the operation originated (`channel`, max 45). Accepted values: `pasarela` (e-commerce sales), `callcenter` (telepago / phone sales), `recurrent` (recurring sales). Note: for stored credential transactions Spreedly overrides this with `recurrent`.	pasarela
external_transaction_id	String	No	Authorize, Purchase, Verify	Unique transaction identifier sent by the merchant (`externalTransactionId`, length 36).	5ca183ca-06a6-4438-80ad-aa82e88c1680
tokenize	Boolean	No	Verify	Spreedly flag requesting Niubiz to tokenize the card during the validate/verify call. Not a documented Niubiz request field. Defaults to false.	true
ruc	String	No (Niubiz marks it required for refunds)	Refund (Credit)	RUC (Registro Único de Contribuyentes / merchant tax ID, 11 digits) of the merchant issuing the refund (`ruc`).	20341198217
annulation_reason	String	No	Void	Reason sent in the void request body (`annulationReason`). Not documented in Niubiz's public Anulación API request table; optional pass-through.	POST_AUTH_USER_DECLINE

📘
Field reference sources: channel, merchant_id/merchantId, external_transaction_id/externalTransactionId — API de Autorización; ruc and comment (Spreedly description) — API de Devoluciones; void endpoint — API de Anulación. tokenize and annulation_reason are Spreedly-side / optional fields not documented by Niubiz.

Gateway Specific Response Fields

<gateway_specific_response_fields>
  <niubiz>
    <transaction_id>990772115513xyz</transaction_id>
    <purchase_number>29645833266</purchase_number>
    <authorization_code>153831</authorization_code>
    <action_code>000</action_code>
    <trace_number>77821</trace_number>
    <signature>2fe2272c-76ec-4526-ac53-f3b2df94d98b</signature>
    <external_transaction_id>abc123xyz</external_transaction_id>
    <token>card_token</token>
  </niubiz>
</gateway_specific_response_fields>

Field Name	Type	Description	Example Value
transaction_id	string	Niubiz transaction identifier for the order (`transactionId`). Used together with `purchase_number` and `signature` to reference the transaction for capture, void, and refund.	990772115513666
purchase_number	string	Niubiz purchase number for the order (`purchaseNumber`, derived from `order_id`).	29645833266
authorization_code	string	Authorization code returned by Niubiz for an approved transaction (`authorizationCode`).	153831
action_code	string	Niubiz action code (`actionCode` / `ACTION_CODE`). `000` and `400` indicate success.	000
trace_number	string	Trace number returned by Niubiz (`traceNumber`, e.g. on void).	77821
signature	string	Fulfillment signature used to void/annul the original transaction (`fulfillment.signature`).	2fe2272c-76ec-4526-ac53-f3b2df94d98b
external_transaction_id	string	Echoes the merchant-supplied external transaction id when provided.	5ca183ca-06a6-4438-80ad-aa82e88c1680
token	string	Card token returned when tokenization is requested on a verify.	7000010038551408

📘
Note
Spreedly's gateway_transaction_id is composed of transaction_id|purchase_number|signature (fields joined with |).

Stored Credentials

Niubiz supports stored credentials (Card on File) using Spreedly's first-class support. Include stored_credential_initiator and stored_credential_reason_type on the Authorize or Purchase request; Spreedly maps them to Niubiz as follows

stored_credential_initiator	stored_credential_reason_type	Niubiz mapping
cardholder	recurring	`card.registerFrequent = true`, `channel = recurrent`
merchant	recurring	`card.useFrequent = true`, `channel = recurrent`, `order.originalResolutorId = <network_transaction_id>`

3DS2 (Global)

Niubiz supports Spreedly 3DS2 Global for purchase and authorize (3dsecure_2_mpi_purchase / 3dsecure_2_mpi_authorize). Pass the authentication result and Spreedly maps it to Niubiz's authentication object

Spreedly 3DS field	Niubiz field	Example Value
ecommerce_indicator (eci)	eci	05
xid	xid	55620190222103928509
authentication_value (cavv)	cavv	0000010148677336601400453067730000000000
three_ds_version	protocolVersion	2.1.0
directory_server_transaction_id	directoryServerTransactionId	97267598-FAE6-48F2-8083-C23433990FBC

📘
Note
Gateway-specific 3DS2 is not supported.

Additional resources

📘
If you need support with this gateway, please contact Support at [email protected].

📘
Niubiz Developer Portal: https://desarrolladores.niubiz.com.pe/
Homepage: https://niubiz.com.pe/
API Endpoint (Production): https://apiprod.vnforapps.com
API Endpoint (Test/Sandbox): https://apisandbox.vnforappstest.com
API Versions: Default API v1, Authorization API v3, Security API v1