juno integration api 2.0 specification2019-11-09 eduardo hamerski 1.0.0 draft 2019-11-09 norton...

JUNO Integration API 2.0

Date Person Version Description

2019-11-09 Eduardo Hamerski 1.0.0 Draft

2019-11-09 Norton Gueno 1.0.0 Revision

2019-11-12 Eduardo Hamerski 1.0.1 Add paymentAdvance to create charge. Rename firstOId to firstObjectId in list charges. Rename lastOId to lastObjectId in list charges.

2019-11-19 Eduardo Hamerski 1.0.2 Add hmac secret to webhook responses. Add payload descriptions.

2019-11-21 Eduardo Hamerski 1.0.3 Update Charge payloads. Create Payment resource. Create Bill Payment resource. Update throttling policies. Update Event Dispatcher headers.

2019-12-03 Norton Gueno 1.0.4 Fix content-type for file upload using form-data (multipart/form-data).

2019-12-06 Eduardo Hamerski 1.0.5 Add CHARGE_READ_CONFIRMATION event. Add digitalAccountId to event payload for: CHARGE_STATUS_CHANGED, PAYMENT_NOTIFICATION.

Summary

1. Introduction 8

1.1. Objectives 8

1.2. Definitions 8

2. Authorization Server 9 Endpoints 9 Expiration Time 9 Throttling Control 9

2.1. API Resources 10

2.1.1. OAuth 10 POST /oauth/token 10

Request 10 Response 10 Example 10

Request 10 Response 10

References 11

3. Resource Server 12 Endpoints 12 Throttling Control 12

3.1. API-Version 13 Request Sample 13

3.2. Resource-Token 14 Request Sample 14

3.3. Non-Idempotent Token 15

3.4. Entity ID Tokenization 16

3.5. Request Template 17 Template 17 Query Parameters for Data Filter & Pagination 17 Pagination Links 17

3.6. API Resources 18

3.6.1. Data 18 Best Practices 18 GET /data/banks 18

Request 18

Response 18 GET /data/company-types 19


GET /data/business-areas 20 Request 20 Response 20

3.6.2. Digital-Accounts 21 POST /digital-accounts 21

Request 21 Response 22 Event Notification 22

Events 22 Payload 23

GET /digital-accounts 24 Request 24 Response 24

3.6.3. Credentials 25 GET /credentials/public-key 25

Request 25 Response 25 Code Sample / Java: Loading a Public Key from a String 25

3.6.4. Documents 26 POST /documents/{id}/files (Form-Data Version) 26



POST /documents/{id}/files (JWE / Encrypted Version) 28 Request 28 Response 28 Event Notification 29


Code Sample / Java: Encoding a File with JWE 30 Main dependency 30 Code 30

References 30 GET /documents 31

Request 31

Response 31 GET /documents/{id} 32


3.6.5. Balance 33 GET /balance 33


3.6.6. Charges 34 POST /charges 34



GET /charges 36 Request 36 Response 36

GET /charges/{id} 38 Request 38 Response 38

PUT /charges/{id}/cancelation 39 Request 39 Response 39

3.6.7. Payments 40 POST /payments 40



POST /payments/{id}/refunds 42 Request 42 Response 42 Event Notification 42

Events 42

3.6.8. Transfers 43 POST /transfers 43


Event Notification 44 Events 44 Payload 44

3.6.9. Bill-Payments 46 POST /bill-payments 46



3.6.10. Credit-Cards 48 POST /credit-cards/tokenization 48


3.6.11. Notifications 49 GET /notifications/event-types 49


GET /notifications/webhooks 50 Request 50 Response 50

GET /notifications/webhooks/{id} 51 Request 51 Response 51

POST /notifications/webhooks 52 Request 52 Response 52

PATCH /notifications/webhooks/{id} 53 Request 53 Response 53

DELETE /notifications/webhooks/{id} 54 Request 54 Response 54

4. Error Handling 55 Payload Definition 55

Example 1 55 Example 2 55

5. Event Publisher 56 Payload Definition 56

6. Event Dispatcher 57 POST {webhook-address}:{port}?{queryStringParameters} 57

Retry Police 57 Request 57 Response 57

7. Payload Description 60

1. Introduction

1.1. Objectives

1.2. Definitions Term Description

RESTFUL API

HATEOAS Response with one object: { "field1": "value1", "field2": "value2", "field3": "value3", ..., "_links": { "self": { "href": ".../{resource}/{id}" }, ... } } Response with an array of objects: { "_embedded": { "objects": [ { ..., "_links": { "self": { "href": "..." } } }, { ..., "_links": { "self": { "href": "..." } } }, { ..., "_links": { "self": { "href": "..." } } }, ... ] }, "_links": { "self": { "href": ".../{resource}" } } }

OAUTH2

JWT JSON WEB TOKEN

JWE JSON WEB ENCRYPTION

AUTHORIZATION SERVER

RESOURCE SERVER

THROTTLING CONTROL

2. Authorization Server The Authorization Server is the component that issues new authorization tokens (JWT = JSON WEB TOKEN) to access Juno's Integration API. As a first step, the client must contact Juno and request his credentials: clientId and clientSecret. Each environment has its own pair of credentials. As a prerequirement, the client must have a valid digital account created for this end. The second step is to call the Authorization Server service to exchange the credentials by an access token.

Endpoints Environment Url

Sandbox https://sandbox.boletobancario.com/authorization-server

Production https://api.juno.com.br/authorization-server

An access token can be used by a limited amount of time. After its expiration the client must request another access token to the Authorization Server. The expiration time is different for each environment.

Expiration Time Environment Expiration Time

Sandbox 86400 seconds (24 hours)

Production 3600 seconds (1 hour)

Throttling Control Integrations must avoid getting an authorization token for each resource call. Integrations must implement abstractions to control the token expiration and only call the authorization server when the token is close to expire. Massive calls to the Authorization Server may be blocked in its source by Juno's network infrastructure and it may stop your integration .

2.1. API Resources

2.1.1. OAuth OAuth is the resource that encompasses the services related to the OAuth pattern. The main service available is /oauth/token that exchanges a pair of credentials by an access token. For this implementation only the access token is available. The refresh token will be delivered in future versions.

POST /oauth/token Exchange a pair of credentials by an access token with authorization to access Juno's Integration API.

Request Line POST /oauth/token HTTP/1.1

Header Authorization: Basic (see references) Content-Type: application/x-www-form-urlencoded

Body grant_type=client_credentials

Response

Body { "access_token": "", "token_type": "bearer", "expires_in": , "scope": "all", "user_name": "", "jti": "" }

Example clientId: exemplo-client-id clientSecret: exemplo-client-secret

Request

Line POST /oauth/token HTTP/1.1

Header Authorization: Basic ZXhlbXBsby1jbGllbnQtaWQ6ZXhlbXBsby1jbGllbnQtc2VjcmV0 Content-Type: application/x-www-form-urlencoded

Body grant_type=client_credentials

Base64("exemplo-client-id:exemplo-client-secret") = ZXhlbXBsby1jbGllbnQtaWQ6ZXhlbXBsby1jbGllbnQtc2VjcmV0

Response

Status Line HTTP/1.1 200 OK

Body { "access_token":

"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXvCJ9.eyJ1c2VyX25hbWUiOiJ1c2VyQGRvbWFpbi5jb20iLCJzY29wZSI6WyJhbGwiXSwiZXhwIjoxNTczMDcsMDUyLCJqdGkiOiI5NzNhMGY1Yi01NzBmLTQ5OTMtYmViZi1iNTZmZGQyMjgwNGQiLCJjbGllbnRfaWQiOialeGVtcGxvLWNsaWVudC1pZCJ9.aI8b3TqmoXKN9JZG27t64z6GBM7u9BmcDoELvBmXOAnT_g-NZ3qo83ptpTtZXHGOzx7J0hFdzVZ60feCN7gBfM-UhOwKaRwKJwmA41ZPqNyInoRBieuLCrBua8DwNHJ-BroQBWvXgeuFmyukqz1nRGoJTMuov6gbRjThdsYM0pBS4bsLM9QhZEnPkG1C7PSSNBYpvsVdBSvSMWZk8ulrKennMn305O7WPL25W4HyU3RorJK2AyiQ2pYFIDf--QdpFjzALYpwj_WKi0W2noBUKM4lCnHgsgM6ezxO56n68eB5PQzDLtI3CqRgwMgBcys5aLUWO5Y71AjC1rerEOLOOQ",

"token_type": "bearer", "expires_in": 86399, "scope": "all", "user_name": "[email protected]", "jti": "973a0f5b-570f-4993-bebf-b56fdd22804d" }

References

1. The OAuth 2.0 Authorization Framework / Client Authentication: https://tools.ietf.org/html/rfc6749#page-16

2. HTTP Authentication: Basic and Digest Access Authentication: https://tools.ietf.org/html/rfc2617

3. Resource Server The Resource Server is the component where the integration resources are available. All requests must include a valid access token to access these resources and services. To see how to generate an access token, please read the section about Authorization Server.

Endpoints Environment Url

Sandbox https://sandbox.boletobancario.com/api-integration

Production https://api.juno.com.br

Most of the services also requires a resource token to identify the digital account that will be used. Each digital account has its own resource token that is generated when it is created. Digital accounts created by API has its resource token included in the response. To acquire the resource token of an account created by Juno's client panel or to make a token refresh, the client must access its Juno's account and perform these operations at Juno's Integration Tab, Private Token option.

This topic will also describe the main patterns adopted by Juno's Integration API: versioning, resource token, non-idempotent token, entity id tokenization, request template and the resources and services available.

Throttling Control Massive calls to the Resource Server must be avoided. Massive calls to the Resource Server may be blocked in its source by Juno's network infrastructure and it may stop your integration . For services with large data loading (e.g. list of charges) or financial data manipulation (e.g. transfers) it is allowed only 1 active request in the Juno's backend each time for the same digital account.

3.1. API-Version The versioning of the API will be controlled by a request header named 'X-API-Version '. API calls must include this header line to identify the correct version of the API to be used, otherwise the caller will receive a 404 Not Found error. The new adopted version is 2.0.0 and the new API is incompatible with the previous version 1.0.0. Version specification:

● .. ● Only will be used to mark the current API version.

○ The changes in the release number indicates a compatibility break with the previous version.

○ and will be used internally to map key changes in the releases without breaking compatibility.

○ X-API-Version is mandatory: there is no default value.

Request Sample Line GET /balance HTTP/1.1

Header X-API-Version: 2 X-Resource-Token: ...

Body ...

3.2. Resource-Token This token is generated during Digital Account creation via API or by accessing Juno's client panel > Integração > Token Privado . It selects the right Digital Account to be used during an API call and is identified in the request header as 'X-Resource-Token '. Only the integration account with permissions to create new digital Accounts and the digital account owners have access to the generated Resource Tokens. This information is private and safely stored.

This is how a Resource Token seems like:

● E58DE09996195947GFE569F450E389F7D50466SA8BCC81283460R3C7708A987W It is important to keep in mind that the resource token identifies the digital account that will be used by the service. For instance, to get the balance of a digital account, send the private token of that digital account. To transfer a value from client A to client B, send the client A's private token, while the client B information will be sent in the request payload. To create a new digital account, send the private token from your integration digital account.

Request Sample Line GET /balance HTTP/1.1

Header X-API-Version: 2 X-Resource-Token: E58DE09996195947GFE569F450E389F7D50466SA8BCC81283460R3C7708A987W ...

Body ...

3.3. Non-Idempotent Token [NOT IMPLEMENTED] Define a mechanism to avoid duplication of resources. Scenario:

● A client requests a charge creation. The operation fails on the client side, but there is no information about its state on the server side. The cliente re-submit the request and the charge is duplicated because the previous operation was successfully completed.

From https://www.restapitutorial.com/lessons/idempotency.html :

● "From a RESTful service standpoint, for an operation (or service call) to be idempotent, clients can make that same call repeatedly while producing the same result. In other words, making multiple identical requests has the same effect as making a single request. Note that while idempotent operations produce the same result on the server (no side effects), the response itself may not be the same (e.g. a resource's state may change between requests)."

● "The PUT and DELETE methods are defined to be idempotent. However, there is a caveat on DELETE. The problem with DELETE, which if successful would normally return a 200 (OK) or 204 (No Content), will often return a 404 (Not Found) on subsequent calls, unless the service is configured to "mark" resources for deletion without actually deleting them. However, when the service actually deletes the resource, the next call will not find the resource to delete it and return a 404. However, the state on the server is the same after each DELETE call, but the response is different."

● "GET, HEAD, OPTIONS and TRACE methods are defined as safe, meaning they are only intended for retrieving data. This makes them idempotent as well since multiple, identical requests will behave the same."

By exclusion, POST method is non-idempotent, which means each call will create a new resource. Solution 1:

● Non-Idempotency Token ● The client sends a token to identify non-idempotent operations. The token must be unique

within its expiration constraints (e.g. 24h), which means operations with the same non-idempotent token will be considered the same operation. If the non-idempotent token already exists, then the operation was already completed and only the result has to be returned. If the token does not exist, the operation must be completed, the token registered and the result returned.

Solution 2:

● Transaction Hash ● A hash is generated for each requested operation based on its content: header, payload, etc.

The hash could be valid within some time restrictions, which means collisions inside that time restriction represent the same operation being requested again. In this case, just return the result. If there is no collision, complete the operation, register the hash and return the result. It is an optimized version for a simple attribute comparison (not so simple!).

3.4. Entity ID Tokenization All entity ids exchanged via API will be tokenized to avoid internal structure and entity identification exposition. The integrations must rely on these tokens to keep track of relationships between internal structures and Juno's objects. Each token will be prefixed to identify the original related entity and internally each token has identified the original related entity. In other words, prefix always has to match with internal entity identification.

Specification:

● prefix = "doc" | "wbh" | "chr" | "pay" | "evt" | … ● suffix = ● token = + "_" + ● The length of the token is related to the length of the entity id.

○ For a Long.MAX_VALUE it is equals to 67 characters. Current definitions:

● dac = DIGITAL_ACCOUNT ● doc = DOCUMENT ● chr = CHARGE ● pay = PAYMENT ● bil = BILL_PAYMENT ● trf = TRANSFER ● p2p = P2P_TRANSFER ● wbh = WEBHOOK ● evt = EVENT_TYPE

Token samples:

● wbh_119F8D9C7C6CB925 ● evt_BDCA582F3FFAD5A4 ● chr_B297EC45B454299B ● doc_B297EC45B454299B ● pay_B297EC45B454299B

3.5. Request Template This section shows the request structure adopted for all requests.

Template Line HTTP/1.1

Header Authorization: Bearer X-API-Version: X-Resource-Token: Content-Type: application/json ...

Body

Query Parameters for Data Filter & Pagination The main parameters are listed below. Each service may define its own set of filters and parameters beyond these ones.

page The number of the page. Default: 1

pageSize Number of items per page. Default: 20 / Max: 100

orderBy Sorting field / depends on the service. Default: id

orderAsc Asc or desc sorting. Default: false

firstObjectId The first tokenized id in the list. Used to get the previous page.

N/A

firstValue The first value based on the specified orderBy field. If the orderBy=id, then firstValue=firstObjectId.

N/A

lastObjectId The last tokenized id in the list. Used to get the next page.

N/A

lastValue The last value based on the specified orderBy field. If the orderBy=id, then lastValue=lastObjectId.

N/A

Pagination Links List of resources will include links (Hateoas Pattern) to turn easier to navigate between previous and next pages. It is NOT possible to address specific pages and there is NO information about how many pages there are. "_links": { "self": { "href": ".../charges?lastObjectId=chr_2B1F3ABA6CABB8&lastValue=chr_2B1F3ABA6CABB8&page=2" }, "previous": { "href": ".../charges?firstObjectId=chr_A0220B7C6D581D&firstValue=chr_A0220B7C6D5810&page=1" }, "next": { "href": ".../charges?lastObjectId=chr_D1DE33CA704771&lastValue=chr_D1DE33CA704771&page=3" } }

3.6. API Resources

3.6.1. Data Set of services to get generic data to feed onboarding processes for integration points.

Best Practices ● Cache

○ Data collected through these services must be cached on integration's side. ● Update

○ These services must be called at most once a day.

GET /data/banks Return the list of banks supported by Juno.

Request Line GET /data/banks HTTP/1.1

Header Authorization: Bearer X-API-Version:

Body N/A

Response


Body { "_embedded": { "banks": [ { "number": "001", "name": "Banco do Brasil" }, ... ] }, "_links": { "self": { "href": ".../data/banks" } } }

GET /data/company-types Return the list of company types supported by Juno.

Request Line GET /data/company-types HTTP/1.1


Body N/A

Response


Body { "companyTypes": [ "MEI", "EI", "EIRELI", "LTDA", "SA", "INSTITUTION_NGO_ASSOCIATION" ], "_links": { "self": { "href": ".../data/company-types" } } }

GET /data/business-areas Return the list of business areas (category & activity) supported by Juno.

Request Line GET /data/business-areas HTTP/1.1


Body N/A

Response


Body { "_embedded": { "businessAreas": [ { "code": 1000, "activity": "Produtos", "category": "Acessorios automotivos" }, ... ] }, "_links": { "self": { "href": ".../data/business-areas" } } }

3.6.2. Digital-Accounts

POST /digital-accounts Create a new digital account. There are two types of digital accounts:

● PAYMENT ○ A fully functional payment digital account. ○ All features available.

● RECEIVING ○ A specific digital account only used for receivings. ○ Just receiving features available.

Request Line POST /digital-accounts HTTP/1.1

Header Authorization: Bearer X-API-Version: X-Resource-Token: Content-Type: application/json

Body [type=PAYMENT]

{ "type": "PAYMENT", "name": "", "document": "", "email": "", "birthDate": "birthDate/format=YYYY-MM-DD/mandatory for individuals>", "phone": "", "businessArea": 1, "linesOfBusiness": "", "companyType": ""2, "legalRepresentative"3: { "name": "", "document": "", "birthDate": "birthDate/format=YYYY-MM-DD>", }, "address": { "street": "", "number": "", "complement": "", "neighborhood": "", "city": "", "state": ""4, "postCode": "" }, "bankAccount": { "bankNumber": "", "agencyNumber": "", "accountNumber": "", "accountComplementNumber": ""5, "accountType": "CHECKING|SAVINGS", "accountHolder": { "name": "", "document": "" } }, "emailOptOut" : 6, "autoApprove" : 6,

"autoTransfer": 6 }

Body [type=RECEIVING]

{ "type": "RECEIVING", "name": "", "document": "", "email": "", "birthDate": "birthDate/format=YYYY-MM-DD/mandatory for individuals>", "phone": "", "businessArea": 1, "companyType": ""2 , "tradingName": "", "businessUrl": "", "legalRepresentative"3: { "name": "", "document": "", "birthDate": "birthDate/format=YYYY-MM-DD>", }, "address": { "street": "", "number": "", "complement": "", "neighborhood": "", "city": "", "state": ""4, "postCode": "" }, "bankAccount": { "bankNumber": "", "agencyNumber": "", "accountNumber": "", "accountComplementNumber": ""5, "accountType": "CHECKING|SAVINGS", "accountHolder": { "name": "", "document": "" } } }

1. See 'GET /data/business-areas' or the table at https://www.boletobancario.com/boletofacil/integration/business-area-id.html . 2. See 'GET /data/company-types' or: "MEI", "EI", "EIRELI", "LTDA", "SA", "INSTITUTION_NGO_ASSOCIATION". 3. Legal Representative is mandatory for Companies. 4. AC, AL, AP, AM, BA, CE, DF, ES, GO, MA, MT, MS, MG, PA, PB, PR, PE, PI, RJ, RN, RS, RO, RR, SC, SP, SE, TO. 5. Account Complement Number is mandatory for bankNumber=104 (Caixa Economica Federal). 6. Advanced Permissions must be requested to Juno.

Response Status Line HTTP/1.1 200 OK

Body { "id": "dac_90726F31D8C6B1A7", "resourceToken": "3CE301DBCC5EC2E73B42869A2616A80BEDEA3FF04473F49F", "_links": { "self": { "href": ".../digital-accounts" } } }

Event Notification

Events ● DIGITAL_ACCOUNT_STATUS_CHANGED

○ ACTIVE ○ AWAITING_DOCUMENTS ○ VERIFIYING ○ VERIFIED ○ BLOCKED ○ INACTIVE

Payload

Body

{ "eventId": "f796aa16-3801-4a8b-b2f6-daff78c6bb3b", "eventType": "DIGITAL_ACCOUNT_STATUS_CHANGED", "timestamp": "2019-10-31T15:34:18.607-03:00", "data": [ { "entityId": "dac_978CD4F256A3FFE7D", "entityType": "DIGITAL_ACCOUNT", "attributes": { "previousStatus": "AWAITING_DOCUMENTS", "status": "VERIFYING" } } ] }

GET /digital-accounts Get data from the digital account identified by X-Resource-Token ..

Request Line GET /digital-accounts HTTP/1.1

Header Authorization: Bearer X-API-Version: X-Resource-Token:

Body N/A

Response


Body { "id": "dac_90726F31D8C6B1A7", "resourceToken": "3CE301DBCC5EC2E73B42869A2616A80BEDEA3FF04473F49F", "_links": { "self": { "href": ".../digital-accounts" } } }

3.6.3. Credentials

GET /credentials/public-key Get the public key associated with a digital account. When a digital account is created, a pair of keys (public/private) is also created for the new digital account. The public key can be requested to enable data encryption exchange between integration backend and Juno's backend (e.g. file upload / jwe).

Request Line GET /credentials/public-key HTTP/1.1


Body N/A

Response


Header Content-Type: plain/text Content-Disposition: attachment; filename="public-key.txt"

Body -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAlyRO1fkWZ1a4EveXAB5iah60SahHm2cw DpG3b4fZ9Jnxmje+oRjQIRE0wjsmZqlrL3Bw2qQ+KDPKd5i2TGoTbfPjSnLMp/9QdPhPa2I27FkZ kJf11hE/csXtnxNDGyTRPov/2vF9Z6INYRvoMBXh5ujnCXFwGS8PyugsHZ4XaM5uJjbRhm+krDXB hLkMP8tYXba1K9o0eWJiAXGlfVT+EEYterCgiKPoKm/IhLa4w7a05/jo9XLeBowdxEktwhOZnMrK +BE02gfD0KfBIj0WoV7oSBsCTU4HEqdQunTKeMPmAnGw5t6wMvJcjcUFnRZJWMJLcipL4OiRweW2 Pv9WfwIDAQAB -----END PUBLIC KEY-----

Code Sample / Java: Loading a Public Key from a String ... // WITHOUT '-----BEGIN PUBLIC KEY-----' and '-----END PUBLIC KEY-----'! String strPublicKey = "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAlyRO1fkWZ1a4EveXAB5iah60SahHm2cw\n" + "DpG3b4fZ9Jnxmje+oRjQIRE0wjsmZqlrL3Bw2qQ+KDPKd5i2TGoTbfPjSnLMp/9QdPhPa2I27FkZ\n" + "kJf11hE/csXtnxNDGyTRPov/2vF9Z6INYRvoMBXh5ujnCXFwGS8PyugsHZ4XaM5uJjbRhm+krDXB\n" + "hLkMP8tYXba1K9o0eWJiAXGlfVT+EEYterCgiKPoKm/IhLa4w7a05/jo9XLeBowdxEktwhOZnMrK\n" + "+BE02gfD0KfBIj0WoV7oSBsCTU4HEqdQunTKeMPmAnGw5t6wMvJcjcUFnRZJWMJLcipL4OiRweW2\n" + "Pv9WfwIDAQAB\n"; byte[] encodedPublicKey = Base64.getMimeDecoder().decode(publicKey); X509EncodedKeySpec spec = new X509EncodedKeySpec(encodedPublicKey); KeyFactory kf = KeyFactory.getInstance("RSA"); PublicKey publicKey = kf.generatePublic(spec); ...

3.6.4. Documents A document is a kind of slot where files are attached. First get the available documents/slots. Second upload the right files to the right documents/slots. There are two types of file upload: a conventional one using form date and an encrypted version using JWE. Accepted file extensions: pdf, doc, docx, jpg, jpeg, png, bmp e tiff.

POST /documents/{id}/files (Form-Data Version) Upload a file related to a document. Return the document identification and its new status.

Request Line POST /documents/{id}/files HTTP/1.1

Header Authorization: Bearer X-API-Version: X-Resource-Token: Content-Type: multipart/form-data

Body Parameter name: files Type: form-data (with one or more files)

Response


Body { "id": "doc_E237BC25F4", "type": "ID", "description": "Documento de identificação (RG ou CNH)", "approvalStatus": "VERIFYING", "_links": { "self": { "href": ".../documents/doc_E237BC25F4" }, "upload": { "href": ".../documents/doc_E237BC25F4/files" } } }

Event Notification

Events ● DOCUMENT_STATUS_CHANGED

○ AWAITING ○ VERIFYING ○ APPROVED ○ REJECTED

Payload

Body

{ "eventId": "0699ffc7-13dd-498f-939a-705faae44fa9", "eventType": "DOCUMENT_STATUS_CHANGED", "timestamp": "2019-10-31T08:18:16.082-03:00",

"data": [ { "entityId": "doc_85C551B010E87FA9CE", "entityType": "DOCUMENT", "attributes": { "approvalStatus": "APPROVED", "description": "Contrato Social", "type": "LTDA_DOC" } }, { "entityId": "doc_23E83EF05A77EEE372", "entityType": "DOCUMENT", "attributes": { "approvalStatus": "APPROVED", "description": "Documento de identificação (RG ou CNH)", "type": "ID" } }, { "entityId": "doc_4D9A3EBFD7A2A60343", "entityType": "DOCUMENT", "attributes": { "approvalStatus": "APPROVED", "description": "Selfie com documento de identificação", "type": "SELFIE" } } ] }

POST /documents/{id}/files (JWE / Encrypted Version) Upload a file related to a document. Return the document identification and its new status. This version uses the JWE specification to generate an encrypted token that contains a json object with the file name and the base64 file content to be uploaded. To ensure network performance and increase file size limits, the payload itself must be compressed based on the JWE specification and the generated JWE token must be also compressed with the gzip algorithm before being sent to this service. (see references) File size analysis:

● Based on a 5.3MB file size: ○ JWE token without payload compression: 9.4MB ○ Compressed JWE token without payload compression: 7.1MB ○ JWE token with payload compression: 6.9MB ○ Compressed JWE token with payload compression: 5.2MB

File size limits:

● Current file size limit: 3MB ● New file size limit: 10MB

Encryption configuration:

● Key management algorithm: RSA_OAEP_256 ● Content encryption algorithm: AES_256_GCM

JOSE header configuration: { "alg": "RSA-OAEP-256", "enc": "A256GCM", "zip": "DEF" } Public Key endpoint:

● See 'GET /credentials/public-key'. Payload specification: { "fn": "", "fc": "" }

Request Line POST /documents/{id}/files HTTP/1.1

Header Authorization: Bearer X-API-Version: X-Resource-Token: Content-Type: application/octet-stream Content-Encoding: gzip

Body GZIP( Compressed JWE Token )

Response


Body { "id": doc_933E313E813C6860F7B0, "type": "ID", "description": "Documento de identificação (RG ou CNH)", "approvalStatus": "VERIFYING", "_links": { "self": { "href": ".../documents/doc_933E313E813C6860F7B0" }, "upload": { "href": ".../documents/doc_933E313E813C6860F7B0/files" } } }

Event Notification

Events ● DOCUMENT_STATUS_CHANGED

○ AWAITING ○ VERIFYING ○ APPROVED ○ REJECTED

Payload

Body

{ "eventId": "0699ffc7-13dd-498f-939a-705faae44fa9", "eventType": "DOCUMENT_STATUS_CHANGED", "timestamp": "2019-10-31T08:18:16.082-03:00", "data": [ { "entityId": "doc_85C551B010E87FA9CE", "entityType": "DOCUMENT", "attributes": { "approvalStatus": "APPROVED", "description": "Contrato Social", "type": "LTDA_DOC" } }, { "entityId": "doc_23E83EF05A77EEE372", "entityType": "DOCUMENT", "attributes": { "approvalStatus": "APPROVED", "description": "Documento de identificação (RG ou CNH)", "type": "ID" } }, { "entityId": "doc_4D9A3EBFD7A2A60343", "entityType": "DOCUMENT", "attributes": { "approvalStatus": "APPROVED", "description": "Selfie com documento de identificação", "type": "SELFIE" } } ] }

Code Sample / Java: Encoding a File with JWE

Main dependency

org.bitbucket.b_c jose4j 0.6.5

Code

... PublicKey publicKey = getPublicKeyFromJuno(); // File data String fn = "rg_frente_e_verso.pdf"; String fc = loadFileAsBase64(fn); // Json specification Map map = new HashMap(); map.put("fn", fn); map.put("fc", fc); String content = JsonUtil.toJson(map); ... // JWT token generation JsonWebEncryption jwe = new JsonWebEncryption(); jwe.setAlgorithmHeaderValue(KeyManagementAlgorithmIdentifiers.RSA_OAEP_256); jwe.setEncryptionMethodHeaderParameter(ContentEncryptionAlgorithmIdentifiers.AES_256_GCM); jwe.enableDefaultCompression(); jwe.setKey(publicKey); jwe.setPlaintext(content); String jweToken = jwe.getCompactSerialization(); // JWT token compression ByteArrayOutputStream output = new ByteArrayOutputStream(); GZIPOutputStream gzip = new GZIPOutputStream(output); gzip.write(jweToken.getBytes("UTF-8")); gzip.close(); // Bytes to be sent to the upload endpoint byte[] requestBody = output.toByteArray(); ...

References

1. JSON Web Encryption (JWE) https://tools.ietf.org/html/rfc7516

2. JWT, JWS and JWE for Not So Dummies! (Part I) https://medium.facilelogin.com/jwt-jws-and-jwe-for-not-so-dummies-b63310d201a3

3. JOSE4J (selected devlib) https://bitbucket.org/b_c/jose4j/wiki/Home

GET /documents Get the list of documents/slots available for a specific digital account.

Request Line GET /documents HTTP/1.1


Body N/A

Response


Body { "_embedded": { "documents": [ { "id": "doc_B297EC45B4", "type": "ID", "description": "Documento de identificação (RG ou CNH)", "approvalStatus": "AWAITING", "_links": { "self": { "href": ".../documents/doc_B297EC45B4" }, "upload": { "href": ".../documents/doc_B297EC45B4/files" } } }, { "id": "doc_E237BC25F4", "type": "SELFIE", "description": "Selfie com documento de identificação", "approvalStatus": "AWAITING", "_links": { "self": { "href": ".../documents/doc_E237BC25F4" }, "upload": { "href": ".../documents/doc_E237BC25F4/files" } } } ] }, "_links": { "self": { "href": ".../documents" } } }

GET /documents/{id} Get the documents/slots available for a specific digital account.

Request Line GET /documents/{id} HTTP/1.1


Body N/A

Response


Body { "id": "doc_E237BC25F4", "type": "ID", "description": "Documento de identificação (RG ou CNH)", "approvalStatus": "AWAITING", "_links": { "self": { "href": ".../documents/doc_E237BC25F4" }, "upload": { "href": ".../documents/doc_E237BC25F4/files" } } }

3.6.5. Balance

GET /balance Get the balance available for a specific digital account.

Request Line GET /balance HTTP/1.1


Body N/A

Response


Body { "balance": 7.20, "withheldBalance": 0.00, "transferableBalance": 7.20, "_links": { "self": { "href": ".../balance" } } }

3.6.6. Charges

POST /charges Create a new charge.

Request Line POST /charges HTTP/1.1

Header Authorization: Bearer X-API-Version: X-Resource-Token: Content-Type: application/json

Body { "charge": { "description": "", "references"1: ["", "", ""], "totalAmount"2: , "amount"2: , "dueDate": "", "installments": , "maxOverdueDays": , "fine": , "interest": , "discountAmount": , "discountDays": , "paymentAdvance": , "paymentTypes"3: [ "BOLETO", "CREDIT_CARD" ] }, "billing": { "name": "", "document": "CPF(len=11)|CNPJ(len=14)", "email": "/optional", "secondaryEmail": "

"dueDate": "2019-11-15", "link": "", "checkoutUrl": "", "installmentLink": "", "payNumber": "BOLETO TESTE - Não é válido para pagamento", "amount": 128.00, "billetDetails": { "bankAccount": "0655/46480-8", "ourNumber": "176/40006994-5", "barcodeNumber": "34198807400000128001764000699450655464808000", "portfolio": "176" }, "_links": { "self": { "href": ".../charges/chr_4D7EFCE4B55A7F0694B0AE2BEBB7E5DC" } } } ] } }

Event Notification

Events ● CHARGE_STATUS_CHANGED

○ ACTIVE ○ CANCELLED ○ MANUAL_RECONCILIATION ○ FAILED ○ PAID

Payload

Body

{ "eventId": "43663722-71eb-4c7c-899b-1f0fbbc65d18", "eventType": "CHARGE_STATUS_CHANGED", "timestamp": "2019-10-31T18:57:04.939-02:00", "data": [ { "entityId": "chr_CF624E08B5B39CB9", "entityType": "CHARGE", "attributes": { "digitalAccountId": "dac_831A4A07CD8E52DB", "code": 70000016, "reference": "ref", "amount": "50.00", "status": "ACTIVE", "dueDate": "2019-12-09" } } ] }

● CHARGE_READ_CONFIRMATION

○ EMAIL ○ DOCUMENT ○ UNDEFINED

Payload

Body

{ "eventId": "43663722-71eb-4c7c-899b-1f0fbbc65d18", "eventType": "CHARGE_READ_CONFIRMATION", "timestamp": "2019-10-31T18:57:04.939-02:00", "data": [ {

"entityId": "chr_CF624E08B5B39CB9", "entityType": "CHARGE", "attributes": { "digitalAccountId": "dac_831A4A07CD8E52DB", "code": 70000016, "reference": "ref", "source": "EMAIL" } } ] }

GET /charges Get a list of charges.

Request Line GET /charges HTTP/1.1

Query String Parameters

createdOnStart.............: start created on (format=YYYY-MM-DD) createdOnEnd...............: end created on (format=YYYY-MM-DD) dueDateStart...............: start due date (format=YYYY-MM-DD) dueDateEnd.................: end due date (format=YYYY-MM-DD) paymentDateStart...........: start payment date (format=YYYY-MM-DD) paymentDateEnd.............: end payment date (format=YYYY-MM-DD) showUnarchived.............: show only unarchived charges showArchived...............: show only archived charges showDue....................: show only due charges showNotDue.................: show only not due charges showPaid...................: show only paid charges showNotPaid................: show only unpaid charges showCancelled..............: show only cancelled charges showNotCancelled...........: show only not cancelled charges showManualReconciliation...: show only manually reconciliation charges showNotManualReconciliation: show only not manually reconciliation charges showNotFailed..............: show only not failed charges orderBy....................: order by (accepted: id, dueDate, amount, paymentDate) orderAsc...................: asc/desc (accepted: true, false) pageSize...................: page size (accepted: min=1, max=100, default=20) page.......................: page (Hateoas links)1 firstObjectId..............: first element object id (Hateoas links)1 firstValue.................: first element value (Hateoas links)1 lastObjectId...............: last element object id (Hateoas links)1 lastValue..................: last element value (Hateoas links)1


Body N/A

1. These attributes are controlled by Hateoas links. The integration must access next or previous pages based on the links delivered on each response. The navigation between pages is always relative to the current page and it is not possible to address a specific page containing a correct response without the correct values for these attributes. The attributes firstObjectId and firstValue are used to access the previous page while lastObjectId and lastValue are used to access the next page. The values for firstValue and lastValue depends on the orderBy field. E.g. orderBy=id, firstValue and lastValue will be equal to firstObjectId and lastObjectId; orderBy=dueDate, firstValue and lastValue will be the first dueDate value and the lastDueDate value in the page. In order to generate correct navigation links, each time the search include new filters, the search must be restarted from scratch, removing these attributes from the url .


Body { "_embedded": { "charges": [ { "id": "chr_4D7EFCE4B55A7F0694B0AE2BEBB7E5DC", "code": 40006994, "reference": "ref1", "dueDate": "2019-11-15", "link": "", "checkoutUrl": "", "installmentLink": "", "payNumber": "BOLETO TESTE - Não é válido para pagamento", "amount": 128.00, "billetDetails": { "bankAccount": "0655/46480-8",

"ourNumber": "176/40006994-5", "barcodeNumber": "34198807400000128001764000699450655464808000", "portfolio": "176" }, "payments": [], "_links": { "self": { "href": ".../charges/chr_4D7EFCE4B55A7F0694B0AE2BEBB7E5DC" } } }, { "id": "chr_BAD5202DE500B91AF7BD784F8B0A59C6", "code": 80156721, "reference": "", "dueDate": "2019-11-03", "link": "", "checkoutUrl": "", "installmentLink": "", "payNumber": "BOLETO VENCIDO", "amount": 11.00, "billetDetails": { "bankAccount": "0655/46480-8", "ourNumber": "176/80156721-6", "barcodeNumber": "34194806200000011001768015672160655464808000", "portfolio": "176" }, "payments": [], "_links": { "self": { "href": ".../charges/chr_BAD5202DE500B91AF7BD784F8B0A59C6" } } }, ... ] }, "_links"1: { "self": { "href": ".../charges?page=1" }, "next": { "href": ".../charges ?lastObjectId=chr_145E48470458201AB58C83A7A55FA813 &lastValue=chr_145E48470458201AB58C83A7A55FA813 &page=2" } } }

1. Hateoas links delivered with the response. The integration must use these links to navigate between previous and next pages.

GET /charges/{id} Get the specified charge.

Request Line POST /charges/{id} HTTP/1.1


Body N/A

Response


Body { "_embedded": { "charges": [ { "id": "chr_4D7EFCE4B55A7F0694", "code": 40006994, "reference": "ref1", "dueDate": "2019-11-15", "link": "", "checkoutUrl": "", "installmentLink": "", "payNumber": "BOLETO TESTE - Não é válido para pagamento", "amount": 128.00, "billetDetails": { "bankAccount": "0655/46480-8", "ourNumber": "176/40006994-5", "barcodeNumber": "34198807400000128001764000699450655464808000", "portfolio": "176" }, "payments": [], "_links": { "self": { "href": ".../charges/chr_4D7EFCE4B55A7F0694B0AE2BEBB7E5DC" } } } ] } }

PUT /charges/{id}/cancelation Cancel the specified charge.

Request Line PUT /charges/{id}/cancelation HTTP/1.1


Body N/A

Response

Status Line HTTP/1.1 204 No Content

Body N/A

3.6.7. Payments This resource is specific for payments of charges issued by Juno. It is used with charge issues to enable transparent checkout (e-commerce).

POST /payments Create a payment for the specified charge.

Request Line POST /payments HTTP/1.1


Body { "chargeId: "", "billing": { "email": "", "address": { "street": "", "number": , "complement": "", "neighborhood": "", "city": "", "state": "", "postCode": "" } }, "creditCardDetails": { "creditCardId": "", "creditCardHash": "", "storeCreditCardData": "" } }

Response


Body { "transactionId": "e35fc2648fa33", "installments": 3, "payments": [ { "id": "pay_66344CADB62766D8", "chargeId": "chr_576766505C82C355ECB98E7DE5AE0204", "date": "2019-10-30", "releaseDate": "2019-12-01", "amount": 10.00, "fee": 0.55, "type": "INSTALLMENT_CREDIT_CARD", "status": "CONFIRMED" }, { "id": "pay_45CA8E92B5208E90", "chargeId": "chr_413FC8BB8D33C4862AD2EAE31BA72D1C", "date": "2019-10-30", "releaseDate": "2020-01-01", "amount": 10.00, "fee": 0.55, "type": "INSTALLMENT_CREDIT_CARD",

"status": "CONFIRMED" }, { "id": "pay_BE8ECABAEB46D3CB", "chargeId": "chr_361C0891BF956BB063595ED624665991", "date": "2019-10-30", "releaseDate": "2020-02-01", "amount": 10.00, "fee": 0.55, "type": "INSTALLMENT_CREDIT_CARD", "status": "CONFIRMED" } ] }

Event Notification

Events ● PAYMENT_NOTIFICATION

○ BANK_PAID_BACK ○ CONFIRMED ○ PARTIALLY_REFUNDED ○ CUSTOMER_PAID_BACK ○ DECLINED ○ FAILED ○ NOT_AUTHORIZED

Payload

Body

{ "eventId": "409c9699-140e-4669-a72a-6505aebf554b", "eventType": "PAYMENT_NOTIFICATION", "timestamp": "2019-11-04T16:36:01.415-02:00", "data": [ { "entityId": "pay_2D942AA490BF52F1", "entityType": "PAYMENT", "attributes": { "digitalAccountId": "dac_831A4A07CD8E52DB", "createdOn": "2019-10-25 18:30:13", "date": "2019-10-24 03:00:00", "releaseDate": "2020-01-26 02:00:00", "amount": "16.67", "fee": "0.81", "status": "PARTIALLY_REFUNDED", "type": "INSTALLMENT_CREDIT_CARD", "paybackDate": "2019-11-04 02:00:00", "paybackAmount": "1.67", "charge": { "id": "chr_4A577856E1F64F6E", "code": 100000594, "dueDate": "2019-12-30 02:00:00", "amount": "16.67" } } } ] }

POST /payments/{id}/refunds Create and execute a total or a partial refund of the payment and all its installments already confirmed by the credit card broker.

Request Line POST /payments/{id}/refunds HTTP/1.1


Body N/A

Response


Body { "transactionId": "e35fc2648fa33", "installments": 3, "refunds": [ { "id": "pay_66344CADB62766D8", "chargeId": "chr_576766505C82C355ECB98E7DE5AE0204", "releaseDate": "2019-12-01", "paybackDate": "2019-10-30", "paybackAmount": 10.00, "status": "CUSTOMER_PAID_BACK" }, { "id": "pay_45CA8E92B5208E90", "chargeId": "chr_413FC8BB8D33C4862AD2EAE31BA72D1C", "releaseDate": "2019-12-01", "paybackDate": "2019-10-30", "paybackAmount": 10.00, "status": "CUSTOMER_PAID_BACK" }, { "id": "pay_BE8ECABAEB46D3CB", "chargeId": "chr_361C0891BF956BB063595ED624665991", "releaseDate": "2019-12-01", "paybackDate": "2019-10-30", "paybackAmount": 10.00, "status": "CUSTOMER_PAID_BACK" } ] }

Event Notification

Events ● PAYMENT_NOTIFICATION

○ PARTIALLY_REFUNDED ○ CUSTOMER_PAID_BACK

Payload

Body

{ "eventId": "409c9699-140e-4669-a72a-6505aebf554b", "eventType": "PAYMENT_NOTIFICATION", "timestamp": "2019-11-04T16:36:01.415-02:00",

"data": [ { "entityId": "pay_2D942AA490BF52F1", "entityType": "PAYMENT", "attributes": { "digitalAccountId": "dac_831A4A07CD8E52DB", "createdOn": "2019-10-25 18:30:13", "date": "2019-10-24 03:00:00", "releaseDate": "2020-01-26 02:00:00", "amount": "16.67", "fee": "0.81", "status": "PARTIALLY_REFUNDED", "type": "INSTALLMENT_CREDIT_CARD", "paybackDate": "2019-11-04 02:00:00", "paybackAmount": "1.67", "charge": { "id": "chr_4A577856E1F64F6E", "code": 100000594, "dueDate": "2019-12-30 02:00:00", "amount": "16.67" } } } ] }

3.6.8. Transfers

POST /transfers Create a new transfer. There are three types of transfers:

● DEFAULT_BANK_ACCOUNT ○ Transfer to the default bank account registered in the customer's digital account. ○ The default bank account is also used for automatic transfers.

● BANK_ACCOUNT ○ Transfer to a third party bank account.

● P2P ○ Transfer between Juno's digital accounts.

The X-Resource-Token always identify the sender. For DEFAULT_BANK_ACCOUNT transfers, the recipient is automatically discovered. For BANK_ACCOUNT and P2P transfers, the recipient is indicated in the request payload.

Request Line POST /transfers HTTP/1.1


Body [type=DEFAULT_BANK_ACCOUNT]1

{ "type": "DEFAULT_BANK_ACCOUNT", "amount": }

Body [type=BANK_ACCOUNT]

{ "type": "BANK_ACCOUNT", "name": "", "document": "", "amount": , "bankAccount": { "bankNumber": "", "agencyNumber": "", "accountNumber": "", "accountComplementNumber": "", "accountType": "CHECKING | SAVINGS" } }

Body [type=P2P]2

{ "type": "P2P", "document": "", "amount": }

1. DEFAULT_ACCOUNT_TRANSFER. The payload is totally optional. The amount is also optional if there is a payload. In these cases the amount will be the available balance in the digital account. 2. P2P. The recipient Juno's digital account is located by the document information.


Body [type=DEFAULT_BANK_ACCOUNT] [type=BANK_ACCOUNT]

{ "id": "trf_60DA0E4C88DA2AFB", "digitalAccountId": "dac_831A4A07CD8E52DB", "creationDate": "2019-10-01 16:18:46", "transferDate": null, "amount": 10.00, "status": "REQUESTED", "recipient": { "name": "Name", "document": "12312312312", "bankAccount": { "bankNumber": "001", "agencyNumber": "2344", "accountNumber": "34234234234", "accountType": "CHECKING" } } }

Body [type=P2P]

{ "id": "p2p_63E5B465D0BDA200", "digitalAccountId": "dac_831A4A07CD8E52DB", "creationDate": "2019-10-01 13:31:31", "transferDate": "2019-10-01 13:31:31", "amount": 10.00, "status": "EXECUTED", "recipient": { "name": "Name", "document": "12312312312" } }

Event Notification

Events ● TRANSFER_STATUS_CHANGED

○ REQUESTED ○ NEEDS_CHECK ○ CHECK_FAILED ○ EXECUTED ○ AWAITING_EXECUTION ○ REJECTED ○ INVALID_BANK_ACCOUNT ○ CANCELED

● P2P_TRANSFER_STATUS_CHANGED

○ NEEDS_CHECK ○ CHECK_FAILED ○ EXECUTED ○ CANCELED

Payload

Body [type=DEFAULT_BANK_ACCOUNT] [type=BANK_ACCOU

{ "eventId": "967705e2-8aef-4e5d-a152-ce8911b0b7b2", "eventType": "TRANSFER_STATUS_CHANGED", "timestamp": "2019-10-01T17:25:03.818-03:00", "data": [ {

NT] "entityId": "trf_BC818FB9449C3110", "entityType": "TRANSFER", "attributes": { "digitalAccountId": "dac_831A4A07CD8E52DB", "creationDate": "2019-10-01 17:24:58", "transferDate": null, "amount": "10.00", "status": "REQUESTED", "recipient": { "name": "Name", "document": "12312312312", "bankAccount": { "bankNumber": "001", "agencyNumber": "2344", "accountNumber": "34234234234", "accountType": "CHECKING" } } } } ] }

Body [type=P2P]

{ "eventId": "92850fad-f0c0-4673-a1b8-2d344dd33a31", "eventType": "P2P_TRANSFER_STATUS_CHANGED", "timestamp": "2019-10-01T17:23:19.898-03:00", "data": [ { "entityId": "p2p_715090FAB8E44E6F", "entityType": "P2P_TRANSFER", "attributes": { "digitalAccountId": "dac_831A4A07CD8E52DB", "creationDate": "2019-10-01 17:23:19", "transferDate": "2019-10-01 17:23:19", "amount": "10.00", "status": "EXECUTED", "recipient": { "name": "Name", "document": "12312312312" } } } ] }

3.6.9. Bill-Payments Bill payment resource. It is used to pay bills issued for other sources (not Juno).

POST /bill-payments Pay a bill.

Request Line POST /bill-payments HTTP/1.1


Body

{ "numericalBarCode": "23793381286001335744156000063307380630000010000", "paymentDescription": "Payment Description", "beneficiaryDocument": "08500749911", "dueDate": "2019-11-18", "paymentDate": "2019-11-05", "billAmount": "134.73", "paidAmount": "134.73" }

Response


Body

{ "id": "bil_B2D9BCDEB4E09276", "numericalBarCode": "23793381286001335744156000063307380630000010000", "billAmount": 100.00, "dueDate": "2019-11-18", "billType": "BOLETO", "digitalAccountId": "dac_C4933863FFDB84E3", "paidAmount": 134.73, "paymentDate": "2019-11-05", "paymentDescription": "Payment Description", "beneficiaryDocument": "08500749911", "status": "REQUESTED", "createdOn": "2019-11-05" }

Event Notification

Events ● BILL_PAYMENT_STATUS_CHANGED

○ SCHEDULED ○ REQUESTED ○ EXECUTED ○ AWAITING_EXECUTION ○ CANCELLED ○ FAILED ○ FAILED_INSUFFICIENT_FUNDS

Payload

Body

{ "eventId": "421e6709-d7d1-49dc-a787-2c31bd9892a1", "eventType": "BILL_PAYMENT_STATUS_CHANGED", "timestamp": "2019-11-05T13:47:32.054-02:00", "data": [ { "entityId": "bil_94E6DF1AB7FEF898", "entityType": "BILL_PAYMENT", "attributes": { "numericalBarCode": "23793381286001349851877000063303580640000002000", "billAmount": "20.00", "dueDate": "2019-11-18", "billType": "BOLETO", "digitalAccountId": "dac_C4933863FFDB84E3", "paidAmount": "134.73", "paymentDate": "2019-11-05", "paymentDescription": "Conta malandra", "beneficiaryDocument": "08500749911", "status": "AWAITING_EXECUTION", "createdOn": "2019-11-05" } } ] }

3.6.10. Credit-Cards

POST /credit-cards/tokenization Tokenize a credit-card in the context of the specified digital account.

Request Line POST /transfers HTTP/1.1


Body

{ "creditCardHash": "" }

Response


Body

{ "creditCardId": "", "last4CardNumber": "", "expirationMonth": "", "expirationYear": "" }

3.6.11. Notifications

GET /notifications/event-types Return all event types available in the platform. Only enabled events will be dispatched to subscribed webhooks.

Request Line GET /notifications/event-types HTTP/1.1


Body

N/A

Response


Body

{ "_embedded": { "eventTypes": [ { "id": "evt_D7349EF874A6C2", "name": "DOCUMENT_STATUS_CHANGED", "label": "O status de um documento foi alterado", "status": "ENABLED" } ] }, "_links": { "self": { "href": "/notifications/event-types" } } }

GET /notifications/webhooks Return all webhooks registered for a digital account.

Request Line GET /notifications/webhooks HTTP/1.1


Body N/A

Response


Body

{ "_embedded": { "webhooks": [ { "id": "wh_C05E1AE51D7F2C06", "url": "https://{webhook-address}:{port}?{queryStringParameters}", "secret": "...", "status": "ACTIVE", "eventTypes": [ { "id": "evt_D7349EF874A6C2AB", "name": "DOCUMENT_STATUS_CHANGED", "label": "O status de um documento foi alterado", "status": "ENABLED" } ], "_links": { "self": { "href": "/notifications/webhooks/wh_C05E1AE51D7F2C06" }, "update": { "href": "/notifications/webhooks/wh_C05E1AE51D7F2C06" }, "delete": { "href": "/notifications/webhooks/wh_C05E1AE51D7F2C06" }, "events": { "href": "/notifications/webhooks/wh_C05E1AE51D7F2C06/events" } } } ] }, "_links": { "self": { "href": "/notifications/webhooks" } } }

GET /notifications/webhooks/{id} Return the specified webhook.

Request Line GET /notifications/webhooks/{id} HTTP/1.1


Body N/A

Response


Body

{ "id": "wh_C05E1AE51D7F2C06", "url": "https://{webhook-address}:{port}?{queryStringParameters}", "secret": "...", "status": "ACTIVE", "eventTypes": [ { "id": "evt_D7349EF874A6C2A", "name": "DOCUMENT_STATUS_CHANGED", "label": "O status de um documento foi alterado", "status": "ENABLED" } ], "_links": { "self": { "href": "/notifications/webhooks/wh_C05E1AE51D7F2C06" }, "update": { "href": "/notifications/webhooks/wh_C05E1AE51D7F2C06" }, "delete": { "href": "/notifications/webhooks/wh_C05E1AE51D7F2C06" }, "events": { "href": "/notifications/webhooks/wh_C05E1AE51D7F2C06/events" } } }

POST /notifications/webhooks Create a new webhook and subscribe to one or more events. The webhook URL and event subscription must be unique per resource, which means that each digital account MUST have its own webhook registered. There is no general or global webhook. You can use the same endpoint for all webhook register, with or without query string params. The webhook endpoint must use HTTP over SSL encrypted and start with https://.

Request Line POST /notifications/webhooks HTTP/1.1


Body { "url": "https://{webhook-address}:{port}?{queryStringParameters}", "eventTypes": [ "DOCUMENT_STATUS_CHANGED" ] }

Response


Body

{ "id": "wh_A1524F65A5A12DB4", "url": "https://{webhook-address}:{port}", "secret": "5c81c9a38e5ddf24f0515b351a7c866eb904282de9f46e87302a8c3d0f80263d"1, "status": "ACTIVE", "eventTypes": [ { "id": "evt_D7349EF874A6C2ABA5A72DAD65E38944", "name": "DOCUMENT_STATUS_CHANGED", "label": "O status de um documento foi alterado", "status": "ENABLED" } ], "_links": { "self": { "href": "/notifications/webhooks/wh_A1524F65A5A12DB4" }, "update": { "href": "/notifications/webhooks/wh_A1524F65A5A12DB4" }, "delete": { "href": "/notifications/webhooks/wh_A1524F65A5A12DB4" }, "events": { "href": "/notifications/webhooks/wh_A1524F65A5A12DB4/events" } } }

1. Each registered webhook has its own secret. The secret is used to generate an hmac signature to the event messages dispatched through that specific webhook. Each event sent has the hmac signature in its HTTP header.

PATCH /notifications/webhooks/{id} Update webhook fields: status and eventTypes. At least one field needs to be changed, it is not mandatory to change both at the same time. It is not possible to subscribe to an event which is already subscribed on another webhook, for the given resource. The webhook URL cannot be changed.

Request Line PATCH /notifications/webhooks/{id} HTTP/1.1


Body { "status": "INACTIVE", "eventTypes": [ "CHARGE_CREATED", "PAYMENT_RECEIVED" ] }

Response


Body

{ "id": "wh_C05E1AE51D7F2C06", "url": "https://{webhook-address}:{port}?{queryStringParameters}", "secret": "...", "status": "INACTIVE", "eventTypes": [ { "id": "evt_D7349EF874A6C2A", "name": "DOCUMENT_STATUS_CHANGED", "label": "O status de um documento foi alterado", "status": "ENABLED" } ], "_links": { "self": { "href": "/notifications/webhooks/wh_C05E1AE51D7F2C06" }, "update": { "href": "/notifications/webhooks/wh_C05E1AE51D7F2C06" }, "delete": { "href": "/notifications/webhooks/wh_C05E1AE51D7F2C06" }, "events": { "href": "/notifications/webhooks/wh_C05E1AE51D7F2C06/events" } } }

DELETE /notifications/webhooks/{id} Delete a webhook. This operation does not delete/purge the events already dispatched to it.

Request Line DELETE /notifications/webhooks/{id} HTTP/1.1


Body N/A

Response


Body N/A

4. Error Handling

Payload Definition { "timestamp": "", "status": , "error": "", "details": [ { "field": "", "message": "", "errorCode": "" } ], "path": "" }

Example 1 { "timestamp": "2019-11-08T16:38:14.666-03:00", "status": 401, "error": "Unauthorized", "details": [ { "message": "Full authentication is required to access this resource", "errorCode": "391000" } ], "path": "/balance" }

Example 2 { "timestamp": "2019-11-08T16:39:44.652-03:00", "status": 400, "error": "Bad Request", "details": [ { "field": "charge.description", "message": "O campo 'charge.description' é obrigatório", "errorCode": "431027" }, { "field": "charge.dueDate", "message": "O campo 'charge.dueDate' deve conter uma data maior ou igual à data atual", "errorCode": "431034" }, { "message": "Apenas um dos campos deve ser informado: 'charge.totalAmount' ou 'charge.amount'", "errorCode": "199001" } ], "path": "/charges" }

5. Event Publisher

Payload Definition { "eventId": "", "eventType": "", "timestamp": "", "data": [ { "entityId": "", "entityType": "", "attributes": { ... } }, ... ] }

6. Event Dispatcher

POST {webhook-address}:{port}?{queryStringParameters} Send an event to a webhook address.

Best practices:

● HTTPS (Mandatory) ● Receive. Persist. Return 200 OK. Process later. ● Do not format the request content before verifying hmac signature.

Retry Police One retry every 2h till reach 50 attempts (approx. 4 days).

Request Line POST {webhook-address}:{port}?{queryStringParameters} HTTP/1.1

Header Signature: Content-Type: json/application;charset=UTF8

Body { "eventId": "f2be6b61-0168-46fa-a245-0e01c19ca925", "eventType": "DOCUMENT_STATUS_CHANGED", "timestamp": "2019-10-31T18:57:04.939-02:00" "data": [ { "entityId": doc_B297EC45B454299, "entityType": "DOCUMENT", "attributes": { "type": "ID", "description": "Documento de identificação (RG ou CNH)", "approvalStatus": "AWAITING" } }, { "entityId": doc_B297EC45B45FVG9, "entityType": "DOCUMENT", "attributes": { "type": "SELFIE", "description": "Selfie com documento de identificação", "approvalStatus": "AWAITING" } } ] }

Response

Status Line HTTP/1.1 200 OK1

Body N/A

1. Always return 200 OK when the message could be read. Never send other response based on your internal business rules: invalid signature, data does not pass your business rules, data does not match, etc. The dispatcher expect different return only when the message could not be read: 404 Not Found, 500 Internal Error, connection timeout, etc.

7. Payload Description

Only the transactions w

ith JSON

payload are described below.

7.1. OAuth

[Response] PO

ST /oauth/token O

bject Field

Description

Mandatory

Type Len

Format

Dom

ain

access_token

JSON

Web Token (JW

T) -

String -

- D

iscrete / not enumerable

token_type

Token type -

String -

- D

iscrete: ●

bearer

expires_in

Num

ber of seconds before expire (subtracted from

average latency)

- Long

- -

Discrete:

●Sandbox...: 86400s (24h)

●Production: 3600s ( 1h)

scope

Resource server access scope

- String

- -

Discrete:

●all

user_nam

e M

anager user from Juno's Integration

Account -

String -

EMAIL

Discrete / not enum

erable

jti

JWT unique identifier

- String

- U

ID

Continuous

7.2. Data

[Response] G

ET /data/banks O

bject Field

Description

Mandatory

Type Len

Format

Dom

ain

banks

List of banks supported by Juno -

Array of Banks

- -

Discrete

bank num

ber Bank num

ber -

String -

- C

ontinuous

nam

e Bank nam

e -

String -

- C

ontinuous

[Response] G

ET /data/company-types

Object

Field D

escription M

andatory Type

Len Form

at D

omain

com

panyTypes List of com

pany types supported by Juno -

Array of Strings

- -

Discrete

[Response] G

ET /data/business-areas

Object

Field D

escription M

andatory Type

Len Form

at D

omain

businessAreas

List of business areas supported by Juno -

Array of Business Areas

- -

Discrete

businessArea code

Business area code -

Long -

- C

ontinuous

activity

Activity description -

String -

- C

ontinuous

category

Category description

- String

- -

Continuous

7.3. Digital-Accounts

[Request / Type=PAYM

ENT] PO

ST /digital-accounts O

bject Field

Description

Mandatory

Type Len

Format

Dom

ain

type

Digital account type

Yes String

- -

Discrete:

●PAYM

ENT

nam

e C

ustomer nam

e Yes

String 80

- C

ontinuous

docum

ent C

ustomer docum

ent (C

PF or CN

PJ)

Yes String

18 w

ith/without m

ask C

ontinuous

em

ail C

ustomer em

ail Yes

String 80

- C

ontinuous

birthD

ate C

ustomer birthdate

For individuals D

ate 10

yyyy-MM

-dd C

ontinuous

phone

Custom

er phone Yes

String 16

- C

ontinuous

businessArea

Business area id (see G

ET /data/business-areas)

Yes Long

4 -

Discrete

●link=business-area-id

lineO

fBusiness C

ustomer line of business

Yes String

100 -

Continuous

com

panyType C

ustomer com

pany type For com

panies String

- -

Discrete:

●M

EI ●

EI ●

EIRELI

●LTD

A ●

SA ●

INSTITU

TION

_NG

O_ASSO

CIATIO

N

em

ailOptO

ut Should the custom

er receive email

notifications from Juno?

(default: false) (m

ust have advanced permission)

No

Boolean -

- D

iscrete

autoApprove

Should the customer be autom

atically approved?

No

Boolean -

- D

iscrete

(default: false) (m


autoTransfer

Should the customer have enabled

automatic transfers?

(default: false) (m


No

Boolean -

- D

iscrete

legalR

epresentative C

ustomer legal representative

For companies

Object

- -

-

address

Custom

er address Yes

Object

- -

-

bankAccount

Custom

er default bank account Yes

Object

- -

-

legalRepresentative

name

Legal representative name

For companies

String 80

- C

ontinuous

docum

ent Legal representative docum

ent (C

PF or CN

PJ)

For companies

String 18

with/w

ithout mask

Continuous

birthD

ate Legal representative birthdate

For companies

Date

10 yyyy-M

M-dd

Continuous

address street

Street Yes

String 100

- C

ontinuous

num

ber N

umber

(if there is no number, send "N

/A")

Yes String

30 -

Continuous

com

plement

Com

plement

No

String 35

- C

ontinuous

neighborhood

Neighborhood

No

String 50

- C

ontinuous

city

Valid city code Yes

Long -

- D

iscrete ●

link=código_municípios_ibge

state

Valid Brazilian UF

Yes String

- -

Discrete

postC

ode Valid Brazilian PostC

ode Yes

String 10

- C

ontinuous

bankAccount bankN

umber

Bank number

Yes String

3 -

Continuous

agencyN

umber

Agency number

Yes String

7 -

Continuous

accountN

umber

Account number

Yes String

15 -

Continuous

accountC

omplem

entNum

ber Account com

plement num

ber (C

aixa Econômica Federal)

If bankNum

ber = 104

String 3

- D

iscrete: ●

001 (Conta C

orrente de Pessoa Física) ●

002 (Conta Sim

ples de Pessoa Física) ●

003 (Conta C

orrente de Pessoa Jurídica) ●

006 (Entidades Públicas) ●

007 (Depósitos Instituições Financeiras)

●013 (Poupança de Pessoa Física)

●022 (Poupança de Pessoa Jurídica)

●023 (C

onta Caixa Fácil)

●028 (Poupança de C

rédito Imobiliário)

●043 (D

epósitos Lotéricos) ●

131 (Poupança Integrada)

accountType

Account type Yes

String -

- D

iscrete: ●

CH

ECKIN

G (C

onta corrente) ●

SAVING

S (Conta poupança)

accountH

older Bank account holder

Yes O

bject -

- -

holder nam

e Bank account holder nam

e Yes

String 80

- C

ontinuous

docum

ent Bank account holder docum

ent (C

PF or CN

PJ)

Yes String

18 w

ith/without m

ask C

ontinuous

[Request / Type=R

ECEIVIN

G] PO

ST /digital-accounts

Object

Field D

escription M

andatory Type

Len Form

at D

omain

type


Yes String

- -

Discrete:

●R

ECEIVIN

G

nam

e C

ustomer nam

e Yes

String 80

- C

ontinuous

docum

ent C

ustomer docum

ent (C

PF or CN

PJ)

Yes String

18 w

ith/without m

ask C

ontinuous

em

ail C

ustomer em

ail Yes

String 80

- C

ontinuous

birthD

ate C

ustomer birthdate

For individuals D

ate 10

yyyy-MM

-dd C

ontinuous

phone

Custom

er phone Yes

String 16

- C

ontinuous

businessArea

Business area id (see G

ET /data/business-areas)

Yes Long

4 -

Discrete

●link=business-area-id

com

panyType C

ustomer com

pany type For com

panies String

- -

Discrete:

●M

EI ●

EI ●

EIRELI

●LTD

A ●

SA ●

INSTITU

TION

_NG

O_ASSO

CIATIO

N

tradingN

ame

Trading name

For companies

(Optional)

String 80

- C

ontinuous

businessU

rl Business http url (w

ww

) Yes

String 100

Http U

rl (ww

w)

Continuous

legalR

epresentative C

ustomer legal representative

For companies

Object

- -

-

address

Custom

er address Yes

Object

- -

-

bankAccount

Custom

er default bank account Yes

Object

- -

-

legalRepresentative

name

Legal representative name

For companies

String 80

- C

ontinuous

docum

ent Legal representative docum

ent (C

PF or CN

PJ)

For companies

String 18

with/w

ithout mask

Continuous

birthD

ate Legal representative birthdate

For companies

Date

10 yyyy-M

M-dd

Continuous

address street

Nam

e Yes

String 100

- C

ontinuous

num

ber N

umber

(if there is no number, send "N

/A")

Yes String

30 -

Continuous

com

plement

Com

plement

No

String 35

- C

ontinuous

neighborhood

Neighborhood

No

String 50

- C

ontinuous

city

Valid city code Yes

Long -

- D

iscrete ●

link=código_municípios_ibge

state

Valid Brazilian UF

Yes String

- -

Discrete

postC

ode Valid Brazilian PostC

ode Yes

String 10

- C

ontinuous

bankAccount bankN

umber

Bank number

Yes String

3 -

Continuous

agencyN

umber

Agency number

Yes String

7 -

Continuous

accountN

umber

Account number

Yes String

15 -

Continuous

accountC

omplem

entNum

ber Account com

plement num

ber (C

aixa Econômica Federal)

If bankNum

ber = 104

String 3

- D

iscrete: ●

001 (Conta C

orrente de Pessoa Física) ●

002 (Conta Sim

ples de Pessoa Física) ●

003 (Conta C

orrente de Pessoa Jurídica) ●

006 (Entidades Públicas) ●

007 (Depósitos Instituições Financeiras)

●013 (Poupança de Pessoa Física)

●022 (Poupança de Pessoa Jurídica)

●023 (C

onta Caixa Fácil)

●028 (Poupança de C

rédito Imobiliário)

●043 (D

epósitos Lotéricos) ●

131 (Poupança Integrada)

accountType

Account type Yes

String -

- D

iscrete: ●

CH

ECKIN

G (C

onta corrente) ●

SAVING

S (Conta poupança)

holder

Bank account holder Yes

Object

- -

-

holder nam

e Bank account holder nam

e Yes

String 80

- C

ontinuous

docum

ent Bank account holder docum

ent (C

PF or CN

PJ)

Yes String

18 w

ith/without m

ask C

ontinuous

[Response] PO

ST /digital-accounts

Object

Field D

escription M

andatory Type

Len Form

at D

omain

type


- String

- -

Discrete:

●PAYM

ENT

●R

ECEIVIN

G

id

Digital account id

- String

- O

bject Id -

resourceToken

Digital account R

esource Token -

String -

Resource-Token

-

[Response] G

ET /digital-accounts

Object

Field D

escription M

andatory Type

Len Form

at D

omain

Idem [R

esponse] POST /digital-accounts

[DIG

ITAL_ACC

OU

NT_STATU

S_CH

ANG

ED] Event N

otification

Object

Field D

escription M

andatory Type

Len Form

at D

omain

eventId

Event id -

String -

UID

-

eventType

Event type -

String -

- D

iscrete: ●

DIG

ITAL_ACC

OU

NT_STATU

S_CH

ANG

ED

tim

estamp

Timestam

p -

Timestam

p -

yyyy-MM

-dd'T'HH

:mm

:ss.SSSXXX -

data

List of notified objects -

Array of O

bjects -

- -

object entityId

Entity id -

String -

Object Id

-

entityType

Entity type -

String -

- D

iscrete: ●

DIG

ITAL_ACC

OU

NT

attributes

Object attributes

- O

bject -

- -

attributes type


- String

- -

Discrete:

●PAYM

ENT

●R

ECEIVIN

G

previousStatus

Previous Status -

String -

- D

iscrete: ●

ACTIVE

●AW

AITING

_DO

CU

MEN

TS ●

VERIFYIN

G

●VER

IFIED

●BLO

CKED

●

INAC

TIVE

status

Current status

- String

- -

Discrete:

●AC

TIVE ●

AWAITIN

G_D

OC

UM

ENTS

●VER

IFYING

●

VERIFIED

●

BLOC

KED

●IN

ACTIVE

7.4. Docum

ents

[Response] PO

ST /documents/{id}/files (Form

-Data Version)

Object

Field D

escription M

andatory Type

Len Form

at D

omain

id

Docum

ent id -

String -

Object Id

-

type

Docum

ent Type -

String -

- D

iscrete (Individual): ●

ID

●PR

OFESSIO

NAL_R

ECO

RD

●

ADD

RESS_PR

OO

F ●

SELFIE D

iscrete (Com

pany): ●

EI_DO

C

●M

EI_DO

C

●LTD

A_DO

C

●C

ON

STITUTIO

N_R

ECO

RD

●

EIRELI_D

OC

●

CO

NTR

ACT_AG

REEM

ENT

●C

OM

PANY_FO

RM

ATION

_MEETIN

G_M

INU

TES

description

Docum

ent description -

String -

- D


Docum

ento de identificação (RG

ou CN

H)

●R

egistro profissional ●

Com

provante de residência ●

Selfie com docum

ento de identificação D

iscrete (Com

pany): ●

Requerim

ento de empresário

●C

ertificado MEI

●C

ontrato Social ●

Estatuto Social e Ata atualizada ●

Contrato Social

●C

ontrato

●Ata de assem

bleia de constituição de empresa

approvalStatus

Approval status -

String -

- D

iscrete: ●

AWAITIN

G

●VER

IFYING

●

APPRO

VED

●R

EJECTED

[Response] PO

ST /documents/{id}/files (JW

E / Encrypted Version)

Object

Field D

escription M

andatory Type

Len Form

at D

omain

Idem [R

esponse] POST /docum

ents/{id}/files (Form-D

ata Version)

[Response] G

ET /documents

Object

Field D

escription M

andatory Type

Len Form

at D

omain

documents

- List of docum

ents available to the current digital account.

- Array of D

ocuments

- -

-

document

Idem [R



ata Version)

[Response] G

ET /documents/{id}

Object

Field D

escription M

andatory Type

Len Form

at D

omain

Idem [R



ata Version)

[DO

CU

MEN

T_STATUS_C

HAN

GED

] Event Notification

Object

Field D

escription M

andatory Type

Len Form

at D

omain

eventId

Event id -

String -

UID

-

eventType

Event type -

String -

- D

iscrete: ●

DO

CU

MEN

T_STATUS_C

HAN

GED

tim

estamp

Timestam

p -

Timestam

p -

yyyy-MM

-dd'T'HH

:mm

:ss.SSSXXX -

data

List of notified objects -

Array of O

bjects -

- -

object entityId

Entity id -

String -

Object Id

-

entityType

Entity type -

String -

- D

iscrete: ●

DO

CU

MEN

T

attributes

Object attributes

- O

bject -

- -

attributes type

Docum

ent Type -

String -

- D


ID

●PR

OFESSIO

NAL_R

ECO

RD

●

ADD

RESS_PR

OO

F ●

SELFIE D

iscrete (Com

pany)