The purpose of this documentation is to guide the developer on how to integrate with PayMee, describing the features and methods to be used, listing information to be sent and received as well as providing examples.
\nThe integration mechanism with PayMee is simple, so only intermediate knowledge in Web programming language, HTTP/HTTPS requests and JSON file manipulation are required to successfully deploy the PayMee solution.
\nIn this manual you will find reference to all operations available on the API REST of the PayMee API. These operations must be performed using specific keys (x-api-key and x-api-token) on the respective environment endpoints:
\nProduction Environment
\n\nSandbox Environment
\nhttps://apisandbox.paymee.com.br/
\nTo perform an operation, combine the base URL of the environment with the resource (URI) of the desired operation and send it using the HTTP verb as described in the operation.
\nThe API solution of the PayMee platform was developed with REST technology, which is the market standard and also independent from the technology used by other parties. This way, it is possible to integrate it through the great majority of programming languages, such as: ASP, ASP. Net, Java, PHP, Ruby, Python, etc.
\nAmongst other features, the attributes that stand out the most in the PayMee platform are:
\nNo proprietary apps: it is not necessary to install any applications in the virtual shop environment, under no circumstances.
\nSimplicity: the protocol used is purely HTTPS.
\nEase of testing: the PayMee platform offers a publicly accessible Sandbox environment, which allows the developer to create a test account making it easier and faster to start integration.
\nCredentials: handling of the customer’s credentials (x-api-key and x-api-token) traffics in the header of the HTTP request of the message.
\nSafety: the information exchange always takes place between the store's Server and PayMee's Server, that is, without the buyer’s browser in between.
\nMultiplatform: the integration is performed through the REST Web Service.
\nIntegration is performed through Web Services. The model employed is quite simple: There are two URLs (endpoints) available: a specific one for production (real time operation), and a specific one for testing, called sandbox.
\nThese URLs receive the HTTP messages through the POST, GET or PUT methods. Each message type must be sent to a resource identified through the path.
\nThe current version of PayMee Webservice supports the following payment methods:
\nTo facilitate testing during integration, PayMee offers a Sandbox environment, which is composed by two areas:
\nTest account register
\nTransactional Endpoint
\nAdvantages of using the Sandbox
No affiliation is required to use PayMee's Sandbox. You just have to access the Sandbox Registration, create an account and, with it, receive a x-api-key and a x-api-token, which are the credentials required for the API methods.
You can create your sandbox account here: https://apisandbox.paymee.com.br/register
\nThe Notification Post is sent based on a selection of events to be made in the PayMee registry.
\nThe events that can be notified are:
\nPayMee's send the notifications to the URL that you have configured using the HTTP protocol, by the POST method.
\nAuthentication
\nBasic http auth.
The username is your x-api-key and password is your x-api-token
Base64 Basic Auth reference:
\nx-api-key = af38b751-30d7-4261-a9fb-ea30f6ece609
\nx-api-token = 28331f43-e2b3-4078-9502-5f656fb66cdf
\nHere is an example of a notification sent by PayMee (the lines have been broken for ease of reading):
\nPOST /callback HTTP/1.1\nAuthorization: Basic YWYzOGI3NTEtMzBkNy00MjYxLWE5ZmItZWEzMGY2ZWNlNjA5OjI4MzMxZjQzLWUyYjMtNDA3OC05NTAyLTVmNjU2ZmI2NmNkZg==\nContent-Length:272\nContent-Type:application/json\n{\n \"saleToken\": \"d59b39ce-bffd-3f6d-80c4-c376a242afd1\",\n \"referenceCode\":\"0000000000014\",\n \"currency\": \"BRL\",\n \"amount\":100.00,\n \"shopper\":{\n \"id\": \"12911\",\n \"firstName\":\"Teste\",\n \"lastName\":\"Silva\",\n \"email\":\"teste@teste.com.br\",\n \"agency\": \"1234\",\n \"account\": \"123456-0\"\n },\n \"date\":\"2017-07-28 10:48:56\",\n \"newStatus\": \"PAID\"\n}\n\nA Payment Status URL must be registered, so that the notification POST is executed.
\nThe callback URL should return the HTTP status 200. Otherwise PayMee will try again in 60-seconds interval for a maximum of 5 (five) attempts.
\nHere is an example of a notification sent by PayMee (the lines have been broken for ease of reading):
\nPOST /callback?reversing=true&type=reversing HTTP/1.1\nAuthorization: Basic YWYzOGI3NTEtMzBkNy00MjYxLWE5ZmItZWEzMGY2ZWNlNjA5OjI4MzMxZjQzLWUyYjMtNDA3OC05NTAyLTVmNjU2ZmI2NmNkZg==\nContent-Length:272\nContent-Type:application/json\n{\n \"id\": 611212,\n \"uuid\": \"d19b39ce-bffd-3f6d-80c4-c376a242afd3\",\n \"currency\": \"BRL\",\n \"originalAmount\":100.00,\n \"reversedAmount\":100.00,\n \"status\": \"PENDING\",\n \"bankDetails\":{\n \"bank\": \"341 - BANCO ITAÚ-UNIBANCO S.A.\",\n \"branch\":\"0000\",\n \"account\":\"00000-0\"\n },\n \"sale\": {\n \"id\": 611210,\n \"uuid\": \"75e0b5e2-bc3f-4e75-9c52-24096f2e004d\"\n }\n \"creation\": \"2018-04-15 08:33:22\",\n \"receipt\": null,\n \"reason\": \"amount greater than total of sale\"\n}\n\nA Reversal Status URL must be registered (just like the payment notification) and you must enable this feature on your merchant panel, so the notification POST is executed.
\nThis notification occurs two moments:
\nwhen we cannot approve or identify the sale - In this case, we send the status attribute as PENDING;
\nwhen we revert the amount successfully to the customer - In this case, we send the status attribute as PAID
\nThe callback URL should return the HTTP status 200. Otherwise PayMee will try again in 60-seconds interval for a maximum of 5 (five) attempts.
\nHere is an example of a notification sent by PayMee (the lines have been broken for easy reading):
\nPOST /callback?refund=true&type=refund HTTP/1.1\nAuthorization: Basic YWYzOGI3NTEtMzBkNy00MjYxLWE5ZmItZWEzMGY2ZWNlNjA5OjI4MzMxZjQzLWUyYjMtNDA3OC05NTAyLTVmNjU2ZmI2NmNkZg==\nContent-Length:272\nContent-Type:application/json\n{\n \"saleToken\": \"d19b39ce-bffd-3f6d-80c4-c376a242afd3\",\n \"referenceCode\":\"0000000000014\",\n \"currency\": \"BRL\",\n \"originalAmount\":150.00,\n \"reversedAmount\":50.00,\n \"bankDetails\":{\n \"bank\": \"341 - BANCO ITAÚ-UNIBANCO S.A.\",\n \"branch\":\"0000\",\n \"account\":\"00000-0\"\n },\n \"receipt\": \"null\",\n \"status\": \"PAID\",\n \"refund\": {\n \"id\": 611211,\n \"uuid\": fbebcd28-ae51-11e9-a2a3-2a2ae2dbcce4,\n \"status\": \"PAID\",\n \"amount\": 50.00,\n \"creation\": \"2018-04-15 08:33:22\",\n \"creditDate\": \"2018-04-16 10:48:56\"\n }\n \"reason\": \"amount greater than total of sale\",\n \"date\":\"2018-04-16 10:48:56\"\n}\n\nA Refund Status URL must be registered (The same as the payment notification) and you must enable this feature on your merchant panel, so the notification POST is executed.
\nThis notification occurs when:
\nThe callback URL should return the HTTP status 200. Otherwise PayMee will try again in 60-seconds interval for a maximum of 5 (five) attempts.
\nHere is a success example of a notification sent by PayMee (the lines have been broken for ease of reading):
\nPOST /callback?type=payout HTTP/1.1\nAuthorization: Basic YWYzOGI3NTEtMzBkNy00MjYxLWE5ZmItZWEzMGY2ZWNlNjA5OjI4MzMxZjQzLWUyYjMtNDA3OC05NTAyLTVmNjU2ZmI2NmNkZg==\nContent-Length:272\nContent-Type:application/json\n{\n \"success\": true,\n \"message\": \"success\"\n \"id\": 611212,\n \"uuid\": \"d19b39ce-bffd-3f6d-80c4-c376a242afd3\",\n \"currency\": \"BRL\",\n \"amount\":100.00,\n \"status\": \"PAID\",\n \"referenceCode\": \"XPADOA\",\n \"bankDetails\":{\n \"bank\": \"341 - BANCO ITAÚ-UNIBANCO S.A.\",\n \"branch\":\"0000\",\n \"account\":\"00000-0\"\n },\n \"creation\": \"2018-04-15 08:33:22\",\n \"receipt\": \"https://receipts.paymee.com.br/transaction/23e49aa1f7f193395a7f30900f8aeb40a65a9d7dd85e8d05456847b800713546/d19b39ce-bffd-3f6d-80c4-c376a242afd3\",\n}\n\nHere is a error example of a notification sent by PayMee (the lines have been broken for ease of reading):
\nPOST /callback?payout=true HTTP/1.1\nAuthorization: Basic YWYzOGI3NTEtMzBkNy00MjYxLWE5ZmItZWEzMGY2ZWNlNjA5OjI4MzMxZjQzLWUyYjMtNDA3OC05NTAyLTVmNjU2ZmI2NmNkZg==\nContent-Length:272\nContent-Type:application/json\n{\n \"success\": false,\n \"message\": \"Os dados informados não são validos\",\n \"error_code\": \"PE0001\"\n \"id\": 611212,\n \"uuid\": \"d19b39ce-bffd-3f6d-80c4-c376a242afd3\",\n \"currency\": \"BRL\",\n \"amount\":100.00,\n \"status\": \"PENDING\",\n \"referenceCode\": \"XPADOA\",\n \"bankDetails\":{\n \"bank\": \"341 - BANCO ITAÚ-UNIBANCO S.A.\",\n \"branch\":\"0000\",\n \"account\":\"00000-0\"\n },\n \"creation\": \"2018-04-15 08:33:22\",\n \"receipt\": \"https://receipts.paymee.com.br/transaction/23e49aa1f7f193395a7f30900f8aeb40a65a9d7dd85e8d05456847b800713546/d19b39ce-bffd-3f6d-80c4-c376a242afd3\",\n}\n\nA webhook URL must be registered (just like the payment notification) and you must enable this feature on your merchant panel, so the notification POST is executed.
\nTo generate a transaction throught PayMee, it is necessary to send a request using the POST method to the checkout resource, as shown. This example covers the minimum of fields required to be submitted for authorization.
\nTo generate a transaction through PayMee, it is necessary to send a request using the POST method to the checkout resource, as shown. This example covers the minimum of submitted fields required for authorization.
\nTo generate a transaction throught PayMee, it is necessary to send a request using the POST method to the checkout resource, as shown. This example covers the minimum of fields required to be submitted for authorization.
\nOur API collections for checkout requests
\n","_postman_id":"00c80cde-2287-4cfd-a62d-41a1d83ae200"},{"name":"Payouts","item":[{"name":"batch Payout request","id":"094ecf17-b273-473c-844d-6bc40750ca7f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","type":"text","value":"application/json"},{"key":"x-api-key","type":"text","value":"your-x-api-key"},{"key":"x-api-token","type":"text","value":"your-x-api-token"}],"body":{"mode":"raw","raw":"{\n\t\"payments\": [{\n\t\t\"amount\": 1.00,\n\t\t\"referenceCode\": \"X540QG02\",\n\t\t\"email\": \"foo@bar.com\",\n\t\t\"beneficiary\": {\n\t\t\t\"document\": {\n\t\t\t\t\"type\": \"CPF\",\n\t\t\t\t\"number\": \"00000000000\"\n\t\t\t},\n\t\t\t\"bankDetails\": {\n\t\t\t\t\"type\": \"CHECKING\",\n\t\t\t\t\"bankCode\": \"077\",\n\t\t\t\t\"branch\": \"0001\",\n\t\t\t\t\"account\": \"000001-5\"\n\t\t\t}\n\t\t},\n\t\t\"scheduledDate\": \"2020-11-29 15:00:00\",\n\t\t\"notes\": \"example-01\"\n\t},{\n\t\t\"amount\": 1.99,\n\t\t\"referenceCode\": \"X540QG12\",\n\t\t\"email\": \"foo1@bar.com\",\n\t\t\"beneficiary\": {\n\t\t\t\"document\": {\n\t\t\t\t\"type\": \"CPF\",\n\t\t\t\t\"number\": \"00000000001\"\n\t\t\t},\n\t\t\t\"bankDetails\": {\n\t\t\t\t\"type\": \"CHECKING\",\n\t\t\t\t\"branch\": \"7444\",\n\t\t\t\t\"account\": \"000002-2\"\n\t\t\t}\n\t\t},\n\t\t\"scheduledDate\": \"2020-11-25 00:00:00\",\n\t\t\"notes\": \"example-02\"\n\t},{\n\t\t\"amount\": 3.99,\n\t\t\"referenceCode\": \"X540QG22\",\n\t\t\"email\": \"foo2@bar.com\",\n\t\t\"beneficiary\": {\n\t\t\t\"document\": {\n\t\t\t\t\"type\": \"CPF\",\n\t\t\t\t\"number\": \"00000000002\"\n\t\t\t},\n\t\t\t\"bankDetails\": {\n\t\t\t\t\"type\": \"SAVING\",\n\t\t\t\t\"bankCode\": \"104\",\n\t\t\t\t\"branch\": \"7474\",\n\t\t\t\t\"account\": \"000022-0\"\n\t\t\t}\n\t\t},\n\t\t\"notes\": \"saving-account-example\"\n\t}]\n}"},"url":"https://apisandbox.paymee.com.br/v1.1/payout/create/batch","description":"Payouts at PayMee are cash-out transactions;
\nBefore we start, there are some important tips:
\nreference: https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf
\nPayouts at PayMee are cash-out transactions;
\nBefore we start, there are some important tips:
\nyou must have sufficient funds;
\nyou shoud provide a valid and complete beneficiary details
\nRegister your server CIDR for production enviroment
\nreference: https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf
\n;
\nBefore we start, there are some important notes:
\nOur API collection for Payouts requests
\n","_postman_id":"a1ee7733-f6ab-4f40-9049-18a29c5367ab"},{"name":"get available payment methods","id":"399e3335-8d41-45f3-9307-cb9e84cdb0c0","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"x-api-key","value":"{{your-x-api-key}}","type":"text"},{"key":"x-api-token","value":"{{your-x-api-token}}","type":"text"}],"url":"https://{{env}}.paymee.com.br/v1.1/available_payment_methods","description":"To query a transaction, it is necessary to do a GET for the Payment feature as the example.
\nTo query a transaction, it is necessary to do a GET for the Payment feature as the example.
\nCancellation process via API is available only for PENDING sale.
\nRefunding process is available only for PAID sale.
\nTo receive a payment notification, you must send a request using the PUT method for the URI /v1/sandbox with a callbackURL parameter with the notification address, as shown.
\n","urlObject":{"protocol":"https","path":["v1","sandbox"],"host":["apisandbox","paymee","com","br"],"query":[{"key":"callbackURL","value":"https://foo.bar/postback.php"}],"variable":[]}},"response":[{"id":"4559f850-6051-4575-9039-a1d6985b0f60","name":"Callback URL","originalRequest":{"method":"PUT","header":[{"key":"Content-Type","value":"application/json"},{"key":"x-api-key","value":"your-x-api-key"},{"key":"x-api-token","value":"your-x-api-token"}],"body":{"mode":"raw","raw":""},"url":{"raw":"https://apisandbox.paymee.com.br/v1/sandbox?callbackURL=https://you_url_here/postback.php","protocol":"https","host":["apisandbox","paymee","com","br"],"path":["v1","sandbox"],"query":[{"key":"callbackURL","value":"https://you_url_here/postback.php"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json;charset=UTF-8","name":"Content-Type","description":"The mime type of this content"},{"key":"Date","value":"Thu, 11 Jan 2018 19:23:43 GMT","name":"Date","description":"The date and time that the message was sent"},{"key":"Transfer-Encoding","value":"chunked","name":"Transfer-Encoding","description":"The form of encoding used to safely transfer the entity to the user. Currently defined methods are: chunked, compress, deflate, gzip, identity."}],"cookie":[],"responseTime":null,"body":"{\"status\":0,\"message\":\"success\"}"}],"_postman_id":"e73b7af4-787b-4401-96b6-f17dbf593938"},{"name":"request a webhook redeliver","id":"d5d718df-fdcb-490c-83ae-664ab48127a0","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"x-api-key","value":"your-x-api-key","type":"text"},{"key":"x-api-token","value":"your-x-api-token","type":"text"}],"url":"https://apisandbox.paymee.com.br/v1.1/transactions/{transactionUUID}/webhook/redeliver","description":"To request a webhook redeliver, the transaction type must be a SALE and its payment status 'PAID'.
\nReceive all webhook requests with details;
\nRequest a credit transfer using a PENDING REFUND to processing a PENDING SALE
\nGet PIX Payer Details
\nTo renew a transaction throught PayMee, it is necessary to send a request using the PUT method to the checkout resource and a previous transaction UUID, as shown. This example covers the minimum of fields required to be submitted for authorization.
\n