# RivooPay API Reference Base URL: `https://api.rivoopay.com` Auth header: `X-API-KEY: ` --- ## Cobranças (Charges) ### POST /charge/pix — Create PIX QR Code Charge Creates a dynamic PIX charge with QR code. **Optional header:** `Idempotency-Key: ` **Request body:** ```json { "amount": 10000, "customer": { "taxId": "12345678901", "name": "João Silva", "email": "joao@example.com", "phone": "11999999999", "postalCode": "01234000", "address": "Rua ABC", "district": "Centro", "number": "123", "line1": "Apto 101" }, "expiresIn": 3600, "externalId": "ext_charge_123", "devMode": false } ``` | Field | Type | Required | Notes | |-------|------|----------|-------| | amount | number | ✅ | Centavos. Min: 500 (R$ 5,00) | | customer | object | ✅ | See customer object below | | expiresIn | number | ❌ | Seconds. Default: 1800 (30 min) | | externalId | string | ❌ | For idempotency/tracking | | devMode | boolean | ❌ | Default: false | **Response 201:** ```json { "id": "charge_123456", "status": "PROCESSING", "amount": 10000, "brCode": "00020101021226950014br.gov.bcb.pix...", "brCodeBase64": "data:image/png;base64,iVBORw0KGgoAAA...", "url": "https://rivoopay.com/c/charge_123456", "createdAt": "2025-03-24T21:50:20.772Z", "expiresAt": "2025-03-25T21:50:20.772Z", "externalId": "ext_charge_123", "devMode": false } ``` --- ### POST /charge/pix/static — Create Static PIX QR Code Generates a fixed-value static PIX QR code. Ideal for point-of-sale counters. **Request body:** ```json { "amount": 1000 } ``` **Response 201:** ```json { "status": 201, "message": "Static QR code created successfully", "data": { "correlationID": "qrs_abc123", "brCode": "00020126...", "qrCodeImage": "data:image/png;base64,iVBORw0KGgoAAA...", "devMode": false } } ``` --- ### GET /charge/{id} — Get Charge by ID Retrieves full details of a charge. **Path param:** `id` — charge ID (e.g., `charge_123456`) **Response 200:** ```json { "status": 200, "message": "...", "data": { "id": "charge_123456", "total": 100000, "url": "https://rivoopay.com/c/charge_123456", "status": "OPEN", "paymentStatus": "PROCESSING", "devMode": false, "needShipping": false, "expiresAt": "2024-12-04T09:30:00.000Z", "company": { "taxId": "36062381000180", "name": "Empresa Bola Ltda", "color": "#000000" }, "paymentDate": "2024-12-03T10:30:00.000Z", "successUrl": "https://example.com/success", "failedUrl": "https://example.com/failed", "brCode": "00020101021226950014br.gov.bcb.pix...", "brCodeBase64": "data:image/png;base64,iVBORw0KGgoAAA...", "items": [ { "productId": "prod_123456", "companyId": "company_123456", "quantity": 2, "product": { "id": "prod_01F4Z8...", "name": "Produto Bola", "description": "Produto muito bom", "price": 1990, "needShipping": false, "status": "ACTIVE", "sku": "SKU-ABCD-123", "imageUrl": "https://example.com/image.png" } } ], "customer": { "name": "João da Silva", "taxId": "053.054.053-64", "email": "email@email.org", "phone": "41999999999" } } } ``` **paymentStatus values:** `PENDING`, `PROCESSING`, `PAID`, `RECEIVED`, `EXPIRED` --- ### POST /charge/{chargeId}/simulate-payment — Simulate Payment (Dev Mode Only) Marks a dev mode charge as paid. Only works when the charge was created with `devMode: true`. **Path param:** `chargeId` No request body required. **Response 200:** ```json { "id": "charge_123456", "status": "COMPLETED", "paymentStatus": "PAID" } ``` --- ## Link de Pagamento (Payment Links) ### POST /charge/payment-link — Create Payment Link Creates a shareable payment link. Either pass `customerId` (existing) or inline `customer` object (new). **Optional header:** `Idempotency-Key: ` **Request body:** ```json { "total": 100000, "customerId": "customer_123456", "customer": { "taxId": "12345678901", "name": "João Silva", "email": "joao@example.com", "phone": "11999999999", "postalCode": "01234000", "address": "Rua ABC", "district": "Centro", "number": "123", "line1": "Apto 101" }, "successUrl": "https://example.com/success", "failedUrl": "https://example.com/failed", "needShipping": false, "notifyCustomer": true, "devMode": false, "externalId": "ext_123456", "items": [ { "productId": "prod_123456", "quantity": 2 } ] } ``` | Field | Type | Required | Notes | |-------|------|----------|-------| | total | number | ❌ | Centavos. If omitted, calculated from items | | customerId | string | ❌ | Use existing customer | | customer | object | ❌ | Inline customer data (creates new) | | successUrl | string | ❌ | Redirect on success | | failedUrl | string | ❌ | Redirect on failure | | needShipping | boolean | ❌ | Default: false | | notifyCustomer | boolean | ❌ | Send notification to customer | | devMode | boolean | ❌ | Default: false | | externalId | string | ❌ | External tracking ID | | items | array | ❌ | Product items | **Response 201:** ```json { "status": 201, "message": "...", "data": { "id": "charge_123456", "url": "https://rivoopay.com/c/charge_123456", "devMode": false, "total": 100000, "externalId": "ext_123456" } } ``` --- ## Clientes (Customers) ### GET /client — List All Customers Returns all customers for the authenticated company. **Response 200:** Array of customer objects (see schema below). --- ### POST /client — Create Customer **Request body:** ```json { "name": "Cliente Bola", "status": "ACTIVE", "taxId": "05305405364", "email": "bola@email.com", "phone": "41999999999", "address": "Rua Engenheiros Rebouças", "district": "Rebouças", "number": "2000", "postalCode": "80215100", "line1": "Green apartment" } ``` | Field | Type | Required | Notes | |-------|------|----------|-------| | name | string | ✅ | Max 255 chars | | status | enum | ✅ | `ACTIVE` or `INACTIVE` | | taxId | string | ✅ | CPF (11 digits) or CNPJ (14 digits), digits only | | email | string | ✅ | Valid email | | phone | string | ✅ | 10–11 digits, Brazilian format | | address | string | ❌ | Street name | | district | string | ❌ | Neighborhood | | number | string | ❌ | Street number | | postalCode | string | ❌ | 8 digits (CEP) | | line1 | string | ❌ | Complement | **Response 201:** ```json { "id": "clnt_clx1234567890abcdef", "taxId": "053.054.053-64", "name": "Cliente Bola", "email": "bola@email.com", "phone": "41999999999", "status": "ACTIVE", "companyId": "comp_clx9876543210fedcba", "createdAt": "2025-02-03T10:00:00Z", "updatedAt": "2025-02-03T10:00:00Z", "postalCode": "80215100", "address": "Rua Engenheiros Rebouças", "district": "Rebouças", "number": "2000", "line1": "Green apartment" } ``` --- ## Webhooks ### GET /webhook — List Webhooks Returns all webhooks for the authenticated company. ### POST /webhook — Create Webhook **Request body:** ```json { "url": "https://example.com/webhook", "name": "Payment Webhook", "events": ["charge.pending", "charge.paid", "charge.expired"] } ``` Available events: `charge.pending`, `charge.processing`, `charge.paid`, `charge.received`, `charge.expired` **Response 201:** ```json { "id": "67b14aa9-daac-800e-83bf-f1b44468d1d9", "url": "https://example.com/webhook", "name": "Payment Webhook", "companyId": "67b14aa9-daac-800e-83bf-f1b44468d1d9", "status": "ACTIVE", "events": ["charge.pending", "charge.paid"], "createdAt": "2024-02-15T12:34:56Z", "updatedAt": "2024-02-16T12:34:56Z" } ``` ### GET /webhook/{id} — Get Webhook by ID **Path param:** `id` — webhook UUID --- ## Webhook Payload Structure All webhook events deliver a POST with this shape: ```json { "event": "Charge.Paid", "charge": { "id": "chg_abc123", "status": "paid", "total": 10000 } } ``` Event name casing in payload: `Charge.Pending`, `Charge.Processing`, `Charge.Paid`, `Charge.Received`, `Charge.Expired` Implement the receiving endpoint to return HTTP 200 within 30 seconds. Retry policy: 5 attempts at 1m, 5m, 15m, 1h, 6h intervals.