# MPOS Crie transações para maquininhas de cartão (mPOS). ## Endpoint ``` POST /v1/marketplaces/{marketplace_id}/transactions ``` ## Request Body ```json { "payment_locale": "mpos", "payment_type": "credit", "on_behalf_of": "SELLER_ID", "description": "Venda produto XYZ", "notification": "Pague sua compra no mPOS", "installment_plan": { "number_installments": 3 }, "currency": "BRL", "amount": 15000, "lock": true, "terminal": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6", "reference_id": "VENDA-12345" } ``` ## Campos | Campo | Tipo | Obrigatório | Descrição | | ------------------ | ------- | ----------- | ----------------------------------------------- | | `payment_locale` | string | Sim | Sempre `"mpos"` | | `payment_type` | string | Sim | `"credit"` ou `"debit"` | | `on_behalf_of` | string | Sim | ID do vendedor | | `description` | string | Sim | Descrição da venda | | `notification` | string | Não | Mensagem exibida no mPOS (máx 200 chars) | | `installment_plan` | object | Não | Parcelamento (apenas crédito) | | `currency` | string | Sim | Sempre `"BRL"` | | `amount` | integer | Sim | Valor em centavos | | `lock` | boolean | Não | Bloquear mPOS até conclusão (padrão: false) | | `terminal` | string | Não | Serial number do mPOS específico (32 chars hex) | | `reference_id` | string | Não | Identificador externo | ## Request ### cURL ```bash curl --location 'https://api.gopag.com.br/v1/marketplaces/abc123.../transactions' \--header 'Authorization: Bearer SEU_ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "payment_locale": "mpos", "payment_type": "credit", "on_behalf_of": "54f5445fd4544b454654fdf46545465g", "description": "Venda produto XYZ", "notification": "Pague sua compra no mPOS", "installment_plan": { "number_installments": 3 }, "currency": "BRL", "amount": 15000, "terminal": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" }' ``` ### PHP ```php 'mpos', 'payment_type' => 'credit', 'on_behalf_of' => $sellerId, 'description' => 'Venda produto XYZ', 'notification' => 'Pague sua compra no mPOS', 'installment_plan' => [ 'number_installments' => 3 ], 'currency' => 'BRL', 'amount' => 15000, 'lock' => true, 'terminal' => $mposSerialNumber, 'reference_id' => 'VENDA-12345' ]; $ch = curl_init(); curl_setopt_array($ch, [ CURLOPT_URL => "https://api.gopag.com.br/v1/marketplaces/{$marketplaceId}/transactions", CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode($data), CURLOPT_HTTPHEADER => [ "Authorization: Bearer {$accessToken}", 'Content-Type: application/json' ] ]); $response = curl_exec($ch); $transaction = json_decode($response, true); curl_close($ch); ?> ``` ### Python ```python import requests data = { 'payment_locale': 'mpos', 'payment_type': 'credit', 'on_behalf_of': seller_id, 'description': 'Venda produto XYZ', 'notification': 'Pague sua compra no mPOS', 'installment_plan': { 'number_installments': 3 }, 'currency': 'BRL', 'amount': 15000, 'lock': True, 'terminal': mpos_serial, 'reference_id': 'VENDA-12345' } response = requests.post( f'https://api.gopag.com.br/v1/marketplaces/{marketplace_id}/transactions', json=data, headers={'Authorization': f'Bearer {access_token}'} ) transaction = response.json() ``` ## Response ### Status: 201 Created ```json { "id": "abc123def456ghi789...", "status": "pending", "resource": "transaction", "payment_locale": "mpos", "payment_type": "credit", "amount": "150.00", "currency": "BRL", "description": "Venda produto XYZ", "on_behalf_of": "54f5445fd4544b454654fdf46545465g", "installment_plan": { "number_installments": 3 }, "terminal": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6", "reference_id": "VENDA-12345", "created_at": "2025-12-21T14:30:00Z", "updated_at": "2025-12-21T14:30:00Z" } ``` ## Fluxo de Pagamento ``` 1. Sistema cria transação via API ↓ 2. Push notification enviado ao mPOS específico (se terminal informado) ou para todos mPOS do vendedor ↓ 3. Operador vê notificação no mPOS "Pague sua compra no mPOS - R$ 150,00" ↓ 4. Cliente insere/aproxima cartão ↓ 5. mPOS processa pagamento ↓ 6. Webhook notifica status (succeeded/failed) ↓ 7. Sistema libera produto/serviço ``` ## Parcelamento Apenas para `payment_type: credit`: ```json { "installment_plan": { "number_installments": 6 } } ``` **Limites**: * Mínimo: 1 parcela * Máximo: 12 parcelas * Débito: Sempre 1 parcela ### Exemplo - Parcelamento Variável ```php $i, 'valor' => $valorParcela, 'total' => $valor ]; } return $parcelas; } // Para R$ 150,00 $opcoes = calcularParcelas(15000); // Retorna: 1x R$150, 2x R$75, 3x R$50, ... até 12x ou mínimo de R$5 ?> ``` ## Terminal ID ### Formato * **Tamanho**: 32 caracteres * **Tipo**: Hexadecimal (0-9, a-f) * **Exemplo válido**: `a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6` * **Exemplo inválido**: `ABC-123` ❌ ### Obter Terminal ID ```bash # Listar terminais pareados do vendedor GET /v1/marketplaces/{id}/sellers/{seller_id}/terminals ``` ```json { "items": [ { "id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6", "type": "mpos", "model": "D195", "status": "active", "seller_id": "54f5445fd4544b454654fdf46545465g", "paired_at": "2025-12-01T10:00:00Z" } ] } ``` ### Sem Terminal Específico Se `terminal` não for informado, notificação é enviada para **todos** mPOS do vendedor: ```json { "payment_locale": "mpos", "payment_type": "credit", "on_behalf_of": "SELLER_ID", "amount": 5000 // terminal omitido } ``` ## Lock Mode ### `lock: true` (Recomendado) ```json { "lock": true } ``` **Comportamento:** * ✅ mPOS fica bloqueado para outras transações * ✅ Operador não consegue iniciar nova venda até conclusão * ✅ Timeout: 5 minutos * ✅ Previne múltiplas cobranças acidentais **Quando usar:** * Transações de alto valor * Ambientes com múltiplos operadores * Necessidade de garantir conclusão ### `lock: false` ou omitido **Comportamento:** * ❌ mPOS pode receber novas transações * ❌ Transação anterior pode ser cancelada * ✅ Útil para terminais compartilhados em alta rotatividade ## Notificações Personalize a mensagem exibida no mPOS: ```json { "notification": "Mesa 5 - Conta R$ 150,00" } ``` **Boas práticas:** * ✅ Seja claro e objetivo * ✅ Inclua identificador (mesa, pedido, cliente) * ✅ Máximo 200 caracteres * ✅ Use emojis com moderação 🛒 * ❌ Evite informações sensíveis ### Exemplos ```javascript // Restaurante { notification: "Mesa 12 - Conta R$ 85,50" } // Delivery { notification: "Pedido #12345 - Cliente: João Silva" } // Loja { notification: "Venda balcão - 3 itens - R$ 299,90" } // Feira/Evento { notification: "Stand 8 - Artesanato R$ 45,00" } ``` ## Webhooks Após processamento no mPOS: ### Sucesso ```json { "event": "transaction.succeeded", "transaction_id": "abc123...", "payment_locale": "mpos", "payment_type": "credit", "status": "succeeded", "amount": "150.00", "terminal": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6", "card": { "brand": "Visa", "last4": "1111", "entry_mode": "chip" }, "reference_id": "pedido-12345", "approved_at": "2025-12-21T14:35:00Z" } ``` ### Falha ```json { "event": "transaction.failed", "transaction_id": "abc123...", "payment_locale": "mpos", "status": "failed", "error_code": "card_declined", "error_message": "Cartão recusado", "reference_id": "pedido-12345", "failed_at": "2025-12-21T14:35:00Z" } ``` ## Próximos Passos * [Tap to Pay](/developers/transacoes/criar-transacao-maquininhas-e-celular/tap-to-pay.md) * [PINPAD](/developers/transacoes/criar-transacao-maquininhas-e-celular/pinpad.md) * [Link de Pagamento](/developers/transacoes/criar-transacao-checkout-gopag/link-pagamento.md) * [Webhooks](https://github.com/Gestao-Online/gopag-public-docs/blob/master/DEVELOPERS/webhooks/introducao.md) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.gopag.com.br/developers/transacoes/criar-transacao-maquininhas-e-celular/mpos.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.