MaxiPago API Docs

https://www.maxipago.com/developers/apidocs
Admin
MaxiPago API documentation provides developers with resources for integrating payment gateway...
Tokens:7,143
Snippets:49
Trust Score:7.9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Exemplo de Request com Token e Ação de salvar o cartão automaticamente

Source: https://www.maxipago.com/developers/apidocs/transacao-de-zero-dollar

Este exemplo demonstra como enviar uma requisição para uma transação de zero dólar, especificando os detalhes do cartão e as informações para salvá-lo na base de dados do comerciante. É útil para cenários onde se deseja apenas validar o cartão ou tokenizá-lo para futuras transações.

```APIDOC
## Transação de Zero Dollar com Salvamento de Cartão

### Description
Realiza uma transação de zero dólar para validar informações de cartão de crédito e opcionalmente salvá-lo na base do comerciante para uso futuro. Permite definir permissões e datas de expiração para o cartão salvo.

### Method
POST (Implícito, baseado no contexto de requisição de API)

### Endpoint
(Não especificado no texto fonte, mas geralmente seria um endpoint de transação)

### Parameters
#### Request Body
O corpo da requisição é um XML com a seguinte estrutura:

- **transaction-request** (object) - Elemento raiz da requisição.
  - **version** (string) - Versão da API.
  - **verification** (object) - Informações de verificação do comerciante.
    - **merchantId** (string) - ID do comerciante.
    - **merchantKey** (string) - Chave secreta do comerciante.
  - **order** (object) - Detalhes do pedido.
    - **zeroDollar** (object) - Configurações específicas para transação de zero dólar.
      - **processorID** (string) - ID do processador.
      - **referenceNum** (string) - Número de referência do pedido.
      - **transactionDetail** (object) - Detalhes da transação.
        - **payType** (object) - Tipo de pagamento.
          - **creditCard** (object) - Detalhes do cartão de crédito.
            - **number** (string) - Número do cartão de crédito.
            - **expMonth** (string) - Mês de expiração do cartão (MM).
            - **expYear** (string) - Ano de expiração do cartão (YYYY).
            - **cvvNumber** (string) - Código de segurança do cartão.
      - **payment** (object) - Informações de pagamento.
        - **chargeTotal** (string) - Valor total a ser cobrado (neste caso, '00.00' para zero dólar).
      - **saveOnFile** (object) - Configurações para salvar o cartão na base.
        - **customerToken** (string) - Obrigatório. ID único do cadastro do cliente.
        - **onFileEndDate** (string) - Opcional. Data limite para manter o cartão na base (MM/DD/AAAA).
        - **onFilePermission** (string) - Opcional. Duração limite do uso do cartão salvo (ongoing ou use_once).
        - **onFileComment** (string) - Opcional. Comentários adicionais sobre este cartão.
        - **onFileMaxChargeAmount** (string) - Opcional. Valor máximo permitido para cobrança futura deste cartão.

### Request Example
```xml
<transaction-request>
	<version>3.1.1.15</version>
	<verification>
		<merchantId>100</merchantId>
		<merchantKey>secret-key</merchantKey>
	</verification>
	<order>
		<zeroDollar>
			<processorID>1</processorID>
			<referenceNum>123456789</referenceNum>
			<transactionDetail>
				<payType>
					<creditCard>
						<number>4111111111111111</number>
						<expMonth>12</expMonth>
						<expYear>2020</expYear>
						<cvvNumber>999</cvvNumber>
					</creditCard>
				</payType>
			</transactionDetail>
			<payment>
				<chargeTotal>00.00</chargeTotal>
			</payment>
			<saveOnFile>
				<customerToken>999</customerToken>
				<onFileEndDate>12/25/2020</onFileEndDate>
			</saveOnFile>
		</zeroDollar>
	</order>
</transaction-request>
```

### Response
(Não especificado no texto fonte. Geralmente incluiria um status de sucesso ou falha e detalhes da transação ou do cartão salvo.)
```

--------------------------------

### Exemplo de Requisição XML para Salvar Cartão

Source: https://www.maxipago.com/developers/apidocs/requisicoes-de-cadastro/salvar-um-cartao-na-base

Este snippet demonstra a estrutura XML necessária para enviar os dados de um cartão de crédito e informações de cobrança para a API da maxiPago!, a fim de salvá-lo na base para futuras transações.

```xml
<api-request>
<verification>
<merchantId>store-id</merchantId>
<merchantKey>store-key</merchantKey>
</verification>
<command>add-card-onfile</command>
<request>
<customerId>999</customerId>
<creditCardNumber>4111111111111111</creditCardNumber>
<expirationMonth>12</expirationMonth>
<expirationYear>2030</expirationYear>
<billingName>Fulano de tal</billingName>
<billingAddress1>Av. Marcos Penteado de Ulhoa Rodrigues, 939</billingAddress1>
<billingAddress2>11 Andar</billingAddress2>
<billingCity>Barueri</billingCity>
<billingState>SP</billingState>
<billingZip>06360040</billingZip>
<billingCountry>BR</billingCountry>
<billingPhone>01121218536</billingPhone>
<billingEmail>fulano@dominio.com</billingEmail>
<onFilePermissions>ongoing</onFilePermissions>
<onFileMaxChargeAmount>999.00</onFileMaxChargeAmount>
</request>
</api-request>
```

--------------------------------

### Requisição de Transação de Zero Dólar com Salvamento de Cartão

Source: https://www.maxipago.com/developers/apidocs/transacao-de-zero-dollar

Exemplo de requisição XML para uma transação de zero dólar que também salva o cartão do cliente na base para uso futuro. Utilize este snippet para configurar pagamentos recorrentes ou para facilitar futuras compras do cliente.

```xml
<transaction-request>
	<version>3.1.1.15</version>
	<verification>
		<merchantId>100</merchantId>
		<merchantKey>secret-key</merchantKey>
	</verification>
	<order>
		<zeroDollar>
			<processorID>1</processorID>
			<referenceNum>123456789</referenceNum>
			<transactionDetail>
				<payType>
					<creditCard>
						<number>4111111111111111</number>
						<expMonth>12</expMonth>
						<expYear>2020</expYear>
						<cvvNumber>999</cvvNumber>
					</creditCard>
				</payType>
			</transactionDetail>
			<payment>
				<chargeTotal>00.00</chargeTotal>
			</payment>
			<saveOnFile>
				<customerToken>999</customerToken>
				<onFileEndDate>12/25/2020</onFileEndDate>
			</saveOnFile>
		</zeroDollar>
	</order>
</transaction-request>
```

--------------------------------

### Exemplo de Requisição de Transação de Zero Dollar

Source: https://www.maxipago.com/developers/apidocs/transacao-de-zero-dollar

Este snippet demonstra a estrutura XML para realizar uma transação de Zero Dollar, incluindo detalhes de verificação, pedido e pagamento com valor zero.

```xml
<transaction-request>
	<version>3.1.1.15</version>
	<verification>
		<merchantId>100</merchantId>
		<merchantKey>secret-key</merchantKey>
	</verification>
	<order>
		<zeroDollar>
			<processorID>1</processorID>
			<referenceNum>123456789</referenceNum>
			<transactionDetail>
				<payType>
					<creditCard>
						<number>4111111111111111</number>
						<expMonth>12</expMonth>
						<expYear>2020</expYear>
						<cvvNumber>999</cvvNumber>
					</creditCard>
				</payType>
			</transactionDetail>
			<payment>
				<chargeTotal>00.00</chargeTotal>
			</payment>
		</zeroDollar>
	</order>
</transaction-request>
```

--------------------------------

### Success Response for Add Card to File

Source: https://www.maxipago.com/developers/apidocs/requisicoes-de-cadastro/salvar-um-cartao-na-base

This XML response indicates a successful addition of a card to the file. The 'token' field contains a value that must be saved for future use.

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<api-response>
<errorCode>0</errorCode>
<errorMessage></errorMessage>
<command>add-card-onfile</command>
<time>1678288886147</time>
<result>
<token>+Nz2WhppW/KCcvt1DHogeQ==</token>
</result>
</api-response>
```

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<api-response>
    <errorCode>0</errorCode>
    <errorMessage></errorMessage>
    <command>add-card-onfile</command>
    <time>1678288886147</time>
    <result>
        <token>+Nz2WhppW/KCcvt1DHogeQ==</token>
    </result>
</api-response>
```

--------------------------------

### Query Request

Source: https://www.maxipago.com/developers/apidocs

Allows querying orders in the database. The root node of the XML should be <rapi-request/> and it returns <rapi-response/>.

```APIDOC
## POST /ReportsAPI/servlet/ReportsAPI

### Description
Queries orders and transaction data stored in the system.

### Method
POST

### Endpoint
https://testapi.maxipago.net/ReportsAPI/servlet/ReportsAPI

### Request Body
- **XML Payload** (string) - Required - The report request XML, with <rapi-request/> as the root node.

### Request Example
```xml
<rapi-request>
  <!-- Query parameters here -->
</rapi-request>
```

### Response
#### Success Response
- **XML Payload** - The report response XML, with <rapi-response/> as the root node.

#### Response Example
```xml
<rapi-response>
  <!-- Query results here -->
</rapi-response>
```

### Headers
- **Content-Type**: text/xml
- **Charset**: UTF-8
```

--------------------------------

### Add Card on File

Source: https://www.maxipago.com/developers/apidocs/requisicoes-de-cadastro/salvar-um-cartao-na-base

Saves a customer's credit card details to the maxiPago! system, returning a token for future use. This process requires the customer's ID, credit card information, and complete billing address details.

```APIDOC
## POST /UniversalAPI/postAPI

### Description
Saves a customer's credit card details to the maxiPago! system, returning a token for future use. This process requires the customer's ID, credit card information, and complete billing address details.

### Method
POST

### Endpoint
https://testapi.maxipago.net/UniversalAPI/postAPI (Sandbox)
https://api.maxipago.net/UniversalAPI/postAPI (Production)

### Request Body
```xml
<api-request>
    <verification>
        <merchantId>string</merchantId>
        <merchantKey>string</merchantKey>
    </verification>
    <command>add-card-onfile</command>
    <request>
        <customerId>string</customerId>
        <creditCardNumber>string</creditCardNumber>
        <expirationMonth>string</expirationMonth>
        <expirationYear>string</expirationYear>
        <billingName>string</billingName>
        <billingAddress1>string</billingAddress1>
        <billingAddress2>string</billingAddress2>
        <billingCity>string</billingCity>
        <billingState>string</billingState>
        <billingZip>string</billingZip>
        <billingCountry>string</billingCountry>
        <billingPhone>string</billingPhone>
        <billingEmail>string</billingEmail>
        <onFilePermissions>string</onFilePermissions>
        <onFileMaxChargeAmount>string</onFileMaxChargeAmount>
    </request>
</api-request>
```

### Request Example
```xml
<api-request>
    <verification>
        <merchantId>store-id</merchantId>
        <merchantKey>store-key</merchantKey>
    </verification>
    <command>add-card-onfile</command>
    <request>
        <customerId>999</customerId>
        <creditCardNumber>4111111111111111</creditCardNumber>
        <expirationMonth>12</expirationMonth>
        <expirationYear>2030</expirationYear>
        <billingName>Fulano de tal</billingName>
        <billingAddress1>Av. Marcos Penteado de Ulhoa Rodrigues, 939</billingAddress1>
        <billingAddress2>11 Andar</billingAddress2>
        <billingCity>Barueri</billingCity>
        <billingState>SP</billingState>
        <billingZip>06360040</billingZip>
        <billingCountry>BR</billingCountry>
        <billingPhone>01121218536</billingPhone>
        <billingEmail>fulano@dominio.com</billingEmail>
        <onFilePermissions>ongoing</onFilePermissions>
        <onFileMaxChargeAmount>999.00</onFileMaxChargeAmount>
    </request>
</api-request>
```
```

--------------------------------

### add-card-onfile

Source: https://www.maxipago.com/developers/apidocs/requisicoes-de-cadastro/salvar-um-cartao-na-base

Saves a customer's credit card details to the system. This allows for future transactions without requiring the customer to re-enter their card information.

```APIDOC
## POST /add-card-onfile

### Description
Saves a customer's credit card details to the system for future use.

### Method
POST

### Endpoint
/add-card-onfile

### Parameters
#### Request Body
- **merchantId** (string) - Required - ID of the store that identifies the Establishment.
- **merchantKey** (string) - Required - Key associated with the Store ID.
- **command** (string) - Required - Command to be executed. To save a card in the base: add-card-onfile.
- **customerId** (string) - Required - Unique ID of the customer record, returned when the customer was added to the base. Max length: 64 characters.
- **creditCardNumber** (string) - Required - Credit card number to be saved.
- **expirationMonth** (string) - Required - Card expiration month with 2 digits.
- **expirationYear** (string) - Required - Card expiration year with 4 digits.
- **billingName** (string) - Required - Cardholder's name. The name must be exactly as printed on the card, even if the customer already has a record via the add-consumer command. Max length: 26 characters (No special characters allowed).
- **billingAddress1** (string) - Required - Billing address for the card invoice.
- **billingAddress2** (string) - Optional - Billing address complement.
- **billingCity** (string) - Required - City.
- **billingState** (string) - Required - State (UF) of the customer's residence. 2 letters following Brazilian standard. ZZ = Outside Brazil.
- **billingZip** (string) - Required - Postal code without hyphen.
- **billingCountry** (string) - Required - 2-letter country code (ISO 3166-2).
- **billingPhone** (string) - Required - Cardholder's contact phone. With area code, no hyphen or space (e.g., 1112345678).
- **billingEmail** (string) - Required - Cardholder's email address.
- **onFileEndDate** (string) - Optional - Limit date for the saved card usage. Format: MM/DD/AAAA.
- **onFilePermissions** (string) - Optional - Duration limit for the saved card usage. ongoing = indefinitely, use_once = only once after the 1st charge.
- **onFileComment** (string) - Optional - Additional comments about this card.
- **onFileMaxChargeAmount** (string) - Optional - Maximum amount allowed to charge for this card. Decimals separated by a dot ("."). Example: 100.00.

### Request Example
{
  "merchantId": "your_merchant_id",
  "merchantKey": "your_merchant_key",
  "command": "add-card-onfile",
  "customerId": "customer_id_from_add_consumer",
  "creditCardNumber": "1111222233334444",
  "expirationMonth": "12",
  "expirationYear": "2025",
  "billingName": "John Doe",
  "billingAddress1": "123 Main St",
  "billingAddress2": "Apt 4B",
  "billingCity": "Anytown",
  "billingState": "CA",
  "billingZip": "12345",
  "billingCountry": "US",
  "billingPhone": "1112345678",
  "billingEmail": "john.doe@example.com",
  "onFileEndDate": "12/31/2026",
  "onFilePermissions": "ongoing",
  "onFileComment": "Preferred card for recurring payments",
  "onFileMaxChargeAmount": "500.00"
}

### Response
#### Success Response (200)
- **status** (string) - Indicates the success or failure of the operation.
- **message** (string) - A message describing the result of the operation.
- **cardOnFileId** (string) - The unique identifier for the saved card.

#### Response Example
{
  "status": "success",
  "message": "Card saved successfully.",
  "cardOnFileId": "card_token_12345"
}
```

--------------------------------

### Merchant Credentials for API Calls

Source: https://www.maxipago.com/developers/apidocs

Include your store ID and secret key within the <verification> element for authentication in API requests. Ensure your system uses TLS 1.2 or higher for secure communication.

```xml
<verification>
  <merchantId>store-id</merchantId>
  <merchantKey>secret-key</merchantKey>
</verification>
```

--------------------------------

### Registration Request

Source: https://www.maxipago.com/developers/apidocs

Handles registration operations, such as saving a card to the database. The root node of the XML should be <api-request/> and it returns <api-response/>.

```APIDOC
## POST /UniversalAPI/postAPI

### Description
Performs registration operations, including saving customer data and payment methods.

### Method
POST

### Endpoint
https://testapi.maxipago.net/UniversalAPI/postAPI

### Request Body
- **XML Payload** (string) - Required - The API request XML, with <api-request/> as the root node.

### Request Example
```xml
<api-request>
  <!-- Registration details here -->
</api-request>
```

### Response
#### Success Response
- **XML Payload** - The API response XML, with <api-response/> as the root node.

#### Response Example
```xml
<api-response>
  <!-- Registration response details here -->
</api-response>
```

### Headers
- **Content-Type**: text/xml
- **Charset**: UTF-8
```

--------------------------------

### Smartpage! (HTTPS Redirect)

Source: https://www.maxipago.com/developers/apidocs

Handles payment processing via HTTPS redirect for Smartpage! functionality.

```APIDOC
## POST /hostpay/HostPay

### Description
Facilitates payments through an HTTPS redirect using the Smartpage! service.

### Method
POST

### Endpoint
https://testsecure.maxipago.net/hostpay/HostPay

### Request Body
- **Payment Details** (string) - Required - Data required for the Smartpage! transaction, typically sent as form parameters or in the request body.

### Request Example
(Specific request format depends on Smartpage! integration details, often involves form data)

### Response
#### Success Response
- **Redirect** - The user is redirected to a payment page or a confirmation page.

#### Response Example
(Typically a redirect to a URL, not a JSON response)
```

--------------------------------

### Zero Dollar Transaction

Source: https://www.maxipago.com/developers/apidocs/transacao-de-zero-dollar

This endpoint verifies the validity of a credit card without making any charge to the cardholder. It's a transparent process for the cardholder and does not allow for any post-transaction actions.

```APIDOC
## POST /UniversalAPI/postXML

### Description
Initiates a zero-dollar transaction to validate a credit card without charging the customer. This is a pre-authorization step and does not allow for subsequent operations like capture or cancellation.

### Method
POST

### Endpoint
https://[environment].maxipago.net/UniversalAPI/postXML

### Parameters
#### Request Body
- **version** (string) - Required - API version.
- **merchantId** (string) - Required - Merchant ID that identifies the establishment.
- **merchantKey** (string) - Required - Key associated with the Merchant ID.
- **processorID** (string) - Required - Acquirer code that will process this transaction. Currently, the "Zero Dollar" functionality is only available for the "Rede" acquirer (REST).
- **referenceNum** (string) - Required - Establishment's order identifier. This field accepts only alphanumeric values and must be unique.
- **number** (string) - Required - Customer's credit card number.
- **expMonth** (string) - Required - Card expiration month with 2 digits (e.g., January = 01; November = 11).
- **expYear** (string) - Required - Card expiration year with 4 digits.
- **cvvNumber** (string) - Required - Card security code.
- **chargeTotal** (string) - Optional - Transaction amount. For zero-dollar transactions, this should be '00.00'.

### Request Example
```xml
<transaction-request>
	<version>3.1.1.15</version>
	<verification>
		<merchantId>100</merchantId>
		<merchantKey>secret-key</merchantKey>
	</verification>
	<order>
		<zeroDollar>
			<processorID>1</processorID>
			<referenceNum>123456789</referenceNum>
			<transactionDetail>
				<payType>
					<creditCard>
						<number>4111111111111111</number>
						<expMonth>12</expMonth>
						<expYear>2020</expYear>
						<cvvNumber>999</cvvNumber>
					</creditCard>
				</payType>
			</transactionDetail>
			<payment>
				<chargeTotal>00.00</chargeTotal>
			</payment>
		</zeroDollar>
	</order>
</transaction-request>
```

### Response
(Response details not provided in the source text)

```

--------------------------------

### Transaction Request

Source: https://www.maxipago.com/developers/apidocs

Processes Credit Card and Boleto requests. The root node of the XML should be <transaction-request/> and it returns <transaction-response/>.

```APIDOC
## POST /UniversalAPI/postXML

### Description
Processes Credit Card and Boleto payment transactions.

### Method
POST

### Endpoint
https://testapi.maxipago.net/UniversalAPI/postXML

### Request Body
- **XML Payload** (string) - Required - The transaction request XML, with <transaction-request/> as the root node.

### Request Example
```xml
<transaction-request>
  <!-- Transaction details here -->
</transaction-request>
```

### Response
#### Success Response
- **XML Payload** - The transaction response XML, with <transaction-response/> as the root node.

#### Response Example
```xml
<transaction-response>
  <!-- Transaction response details here -->
</transaction-response>
```

### Headers
- **Content-Type**: text/xml
- **Charset**: UTF-8
```

--------------------------------

### Error Response for Add Card to File

Source: https://www.maxipago.com/developers/apidocs/requisicoes-de-cadastro/salvar-um-cartao-na-base

This XML response signifies an error during the card addition process. The 'errorMessage' field provides details about the parsing or validation issue encountered.

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<api-response>
<errorCode>1</errorCode>
<errorMessage>
<![CDATA[Parser Error: URI=null Line=1: cvc-length-valid: Value '30' with length = '2' is not facet-valid with respect to length '4' for type '#AnonType_expirationYear'.]]>
</errorMessage>
<time>1678289027065</time>
</api-response>
```

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<api-response>
    <errorCode>1</errorCode>
    <errorMessage>
        <![CDATA[Parser Error: URI=null Line=1: cvc-length-valid: Value '30' with length = '2' is not facet-valid with respect to length '4' for type '#AnonType_expirationYear'.]]>
    </errorMessage>
    <time>1678289027065</time>
</api-response>
```
Tokens:
Raw