Skip to main content

Create a payment request via QR code

In this tutorial, you will learn how to use the Request to Pay via QR Code API to create a Payment Request. By the end of this tutorial, you will know how to:

  • Create an immediate request to pay 
  • Create a payment request with a due date 
  • Interpret the API response

Before you begin

To use the Request to Pay API, you will need:

  • A registered and fully onboarded Developer Account on the J.P. Morgan Payments Developer Portal.
  • An active project that provides you with the credentials used to make a request. 

Create an immediate request to pay via QR Code

If you have an e-commerce business or want to send your clients an immediate request to pay, you can use the payment request endpoint with a dynamic QR code and immediate expiration.

Tip

A reconciliation ID will be automatically assigned by  J.P. Morgan. To assign your own reconciliation ID, you can send a PUT request to the /payment-requests/{id} endpoint.

Create a request

Create a POST request to the /payments-requests endpoint and specify a payment request with a dynamic QR code and IMMEDIATE expiration in the request body. Here's an example:

Example of a payment request with immediate expiration
curl --request POST \
  --url https://api-mock.payments.jpmorgan.com/receivables/request-to-pay/v1/payment-requests \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: ' \
  --data '{
  "country": "BR",
  "request": {
    "debtor": {
      "name": "JOÃO DA SILVA RIBEIRO",
      "taxInformation": {
        "taxPayerCategory": "INDIVIDUAL",
        "taxId": "81877226220"
      }
    },
    "creditor": {
      "account": {
        "alternateAccountIdentifier": "70204587000136",
        "schemeName": {
          "proprietary": "CNPJ"
        }
      }
    },
    "expirationType": "IMMEDIATE",
    "duration": 1800,
    "paymentAmount": "150.00",
    "currency": "BRL",
    "isAmountAdjustable": false,
    "reference": "QR associated to checkout cart 5423645",
    "additionalInformation": [
      {
        "valueType": "Obs",
        "text": "ImmediateQR-Test"
      }
    ]
  },
  "requestMethodType": "QR_CODE",
  "requestMethod": {
    "qrCodeType": "DYNAMIC",
    "contentType": "IMAGE",
    "correctionLevel": "MEDIUM",
    "imageWidth": 400
  }
}'

Confirm the response

A successful response will return a payload with the payment request confirmation and QR code details. Here's an example:

Example of a payment request response with immediate expiration
Json
{
  "id": "fca7becb133a4501b5aff72d082a1709",
  "revisionNumber": 0,
  "request": {
    "expirationType": "IMMEDIATE",
    "duration": 1800,
    "currency": "BRL",
    "paymentAmount": "150.00",
    "reference": "QR associated to checkout cart 5423645",
    "additionalInformation": [
      {
        "valueType": "Obs",
        "text": "ImmediateQR-Test"
      }
    ],
    "creditor": {
      "name": "Sample JPM Client",
      "shortName": "Sample JPM Client",
      "address": {
        "addressLines": [
          "RUA PADRE TEIXEIRA, 1357 - APT 1"
        ],
        "city": "S. PAULO",
        "state": "SP",
        "postalCode": "13561",
        "country": "BR"
      },
      "account": {
        "alternateAccountIdentifier": "70204587000136",
        "schemeName": {
          "proprietary": "CNPJ"
        }
      }
    },
    "debtor": {
      "name": "JOÃO DA SILVA RIBEIRO",
      "taxInformation": {
        "taxPayerCategory": "INDIVIDUAL",
        "taxId": "81877226220"
      }
    }
  },
  "requestMethodType": "QR_CODE",
  "country": "BR",
  "requestMethod": {
    "image": "iVBORw0KGgoAAAANSUhEUgAAAZAAAAGQAQAAAACoxAthAAAEeklEQVR4Xu2XQZLkNgwEoZOeoZ+K4k/1DJ2ErSyoe3Y2HN7om8MDBt1mU5U85ABib+THI/7c+Pto5NPRyKejkU9HI5+O/zRyhcaS575qvR3rGbHd67lcsa/nrmfaWfMgtTVihMU0C6j912Je2/RR91qBRh7k4Gkog0kC52DzJdmbCiyN/IEoHDFYuEQTUJ8Ib+QfEL7q8/b6cGsPU2w28h1x+Cm/m7ec+pfOneSRX18r2UjWZcHTf5sHqUaM1Lg2zem2XVSBKatn1CVLdxOu0Ug+bUvGn3msJ0brpqh3oDadaeRBfJ+m5+HkTi+fvjVQjWeorRGXJZcCpXip/IKndYgyK5OXocFBuBHGYY0a3Au+YVNUcKtqrZ30/E3yz0auugsQaw7Vsbqv/VOkVGvWaMSDyrRhWjgv29bmC2Envv1dfjhyOxC88WI8bpWntcv54tJdHG4kS2w+Patw4PlZg0e1drDfSDJuak9PZThBnunT7H8h9e2y+OHIwWUhpbATvVWKVObwTzuehqp0a8SIHFJ+M7Eqny8EnNPsOXxmIyCXrUppUo07Lz0aWThf7Xb6qxaNVFny1I9u5dNK1dd1GkXLLMONVFmGxSqJ4adtbf7a9HheGN6//SD52Qg75GPFttzeQUEOwlr4q/JW3UghRwXYkG3VJ3qPKJzFKMmNvBEX4S6NBCQcn9P16XNeXxspRDto5L238LSSZ4TKlXNmdbQC2mlE/6lbGRthUXauQ2J9Ho3qaOcbKcl5vR3Ks96Bj+3hvtbYEf6UaCNpq/MiH/bsUsS5xLpWMT+p20aestROgtQapVOlmKlMIYOAVTdCjmTgWZt6yzE1lOR/j3OWtHYjD6IufvSmijApy5uXIY+UH7XpbCPKDHzSs1rI867FheTl4gTc2vxo5I2UXgW0oAjBdxv+QmrRSPqras+ep9nbntXC7l4oV2ytG8HkhIqwTH9y4RbIaTjn94l6uZGSvGAYjSNxWwU5/Wj310npbiYa4Wmyg2dpnLZ6rHnXm1B6H+EsGinJDtOtz/QJESpOVSngAqsFo5F0bNgtM5F5cGWQ34NHB4Y5pBEQBoaHZ7zCmiV/90vvdr4RIzwa/tyDe8FPz3Dz+jR+nwzLb6TKEo0uyLRMBUrsLMmu0nRxNlKSXXuEZyFBRx+WfLuF9wjOvLZGHsSdW4G79HKOJHMIU7YpXUYjHnRxSC+vuy01E3bwCVily6NGkg61Ur/c3NH63CnRM2hh7fNX2P1XaMRIoNdzqvzcyySpQ8QeobxO+3ZZ/GjE43D/5gU1ktddsbfF1rGVbOQZ0iufj0zyxd7sUKVvqhGvlTkHl6x+61J+U3joBJvHOfJ3C28kry2tdA/msO1JLDjEuGZ6s5FCyiqxleZN56U9oLhnF/8hfpfcyKw33poTsRpYTTfydMUiH6KRL8kHhtm/uSP4x/ty1Y9hLb6auhEh+pjpUpRq6pOwJnVIF6vBlWnkjUQQriQylZTkKsXw9UrC+42AfDga+XQ08ulo5NPRyKfj/4T8AmTla47fMwazAAAAAElFTkSuQmCC",
    "mimeType": "image/png",
    "imageWidth": 400,
    "paymentLink": {
      "id": "6ea59f2b-1d02-4447-8b96-dc49bdcca25f",
      "expirationType": "IMMEDIATE",
      "country": "BR",
      "url": "https://jpmorgan.net/pix/d460b510-0b7c-43d7-a3d3-782663f67bcd",
      "createdAt": "2024-10-01T20:32:10Z",
      "paymentRequestId": "fca7becb133a4501b5aff72d082a1709"
    },
    "text": "00020101021226830014br.gov.bcb.pix2561https://jpmorgan.net/pix/d460b510-0b7c-43d7-a3d3-782663f67bcd5204000053039865802BR5927Sample JPM Client6008S. PAULO62360532fca7becb133a4501b5aff72d082a1709630419a4",
    "qrCodeType": "DYNAMIC"
  },
  "createdAt": "2024-10-01T20:32:10Z",
  "updatedAt": "2024-10-01T20:32:10Z",
  "expiresAt": "2024-10-01T21:02:10Z",
  "status": "ACTIVE"
}

Create a payment request with a due date via QR Code

If you need to create a service bill for services already delivered, such as a utility bill, you can create a payment request with a due date. This type of request supports applying interests, discounts, or penalties as needed.

Tip

A reconciliation ID will be automatically assigned by  J.P. Morgan. To assign your own reconciliation ID, you can send a PUT request to the /payment-requests/{id} endpoint.

Create a request

Create a POST request to the /payments-requests endpoint and specify a payment request with a dynamic QR code and a DUE DATE expiration in the request body. Here's an example:

Example of a payment request with a due date
curl --request POST \
  --url https://api-mock.payments.jpmorgan.com/receivables/request-to-pay/v1/payment-requests \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: ' \
  --data '{
  "country": "BR",
  "request": {
    "debtor": {
      "name": "JOÃO DA SILVA RIBEIRO",
      "address": {
        "type": "ADDR",
        "addressLines": [
          "AV PAULISTA 200"
        ],
        "city": "SÃO PAULO",
        "state": "SP",
        "postalCode": "01311900",
        "country": "BR"
      },
      "email": {
        "address": "joao.silva@gmail.com",
        "type": "PRIMARY"
      },
      "taxInformation": {
        "taxPayerCategory": "INDIVIDUAL",
        "taxId": "81877226220"
      }
    },
    "creditor": {
      "account": {
        "alternateAccountIdentifier": "70204587000136",
        "schemeName": {
          "proprietary": "CNPJ"
        }
      }
    },
    "expirationType": "DUE_DATE",
    "paymentAmount": "150.00",
    "currency": "BRL",
    "paymentDueDate": "2024-11-01",
    "reference": "Invoice for energy bill - 123456",
    "additionalInformation": [
      {
        "valueType": "Obs",
        "text": "QR with Due Date - Test"
      }
    ],
    "interestType": "PERCENTAGE_PER_DAY",
    "interestParameters": {
      "days": "CALENDAR_DAYS",
      "percentage": "5.00"
    },
    "discountType": "PERCENTAGE_TO_DATE",
    "discountParameters": {
      "cutOffDetails": [
        {
          "percentage": "2.00",
          "cutOffDate": "2024-10-02"
        }
      ]
    },
    "penaltyType": "FIXED_AMOUNT",
    "penaltyParameters": {
      "amount": "16.50"
    },
    "reductionType": "FIXED_AMOUNT",
    "reductionParameters": {
      "amount": "20.00"
    },
    "gracePeriod": 30
  },
  "requestMethodType": "QR_CODE",
  "requestMethod": {
    "qrCodeType": "DYNAMIC",
    "contentType": "IMAGE",
    "correctionLevel": "MEDIUM",
    "imageWidth": 400
  }
}'

Confirm the response

A successful response will return a payload containing the payment request confirmation and QR code details. Here's an example:

Response example for a payment request with a due date
Json
{
  "id": "e9d64e8be2f84f74b0bad614405881aa",
  "revisionNumber": 0,
  "request": {
    "expirationType": "DUE_DATE",
    "gracePeriod": 30,
    "paymentDueDate": "2024-11-01",
    "currency": "BRL",
    "paymentAmount": "150.00",
    "interestType": "PERCENTAGE_PER_DAY",
    "interestParameters": {
      "days": "CALENDAR_DAYS",
      "percentage": "5.00"
    },
    "discountType": "PERCENTAGE_TO_DATE",
    "discountParameters": {
      "cutOffDetails": [
        {
          "cutOffDate": "2024-10-02",
          "percentage": "2.00"
        }
      ]
    },
    "penaltyType": "FIXED_AMOUNT",
    "penaltyParameters": {
      "amount": "16.50"
    },
    "reductionType": "FIXED_AMOUNT",
    "reductionParameters": {
      "amount": "20.00"
    },
    "reference": "Invoice for energy bill - 123456",
    "additionalInformation": [
      {
        "valueType": "Obs",
        "text": "QR with Due Date - Test"
      }
    ],
    "creditor": {
      "name": "Sample JPM Client",
      "shortName": "Sample JPM Client",
      "address": {
        "addressLines": [
          "RUA PADRE TEIXEIRA, 1357 - APT 1"
        ],
        "city": "S. PAULO",
        "state": "SP",
        "postalCode": "13561",
        "country": "BR"
      },
      "account": {
        "alternateAccountIdentifier": "70204587000136",
        "schemeName": {
          "proprietary": "CNPJ"
        }
      }
    },
    "debtor": {
      "name": "JOÃO DA SILVA RIBEIRO",
      "address": {
        "type": "ADDR",
        "addressLines": [
          "AV PAULISTA 200"
        ],
        "city": "SÃO PAULO",
        "state": "SP",
        "postalCode": "01311900",
        "country": "BR"
      },
      "taxInformation": {
        "taxPayerCategory": "INDIVIDUAL",
        "taxId": "81877226220"
      },
      "email": {
        "address": "joao.silva@gmail.com",
        "type": "PRIMARY"
      }
    }
  },
  "requestMethodType": "QR_CODE",
  "country": "BR",
  "requestMethod": {
    "image": "iVBORw0KGgoAAAANSUhEUgAAAZAAAAGQAQAAAACoxAthAAAFKklEQVR4Xu2aMW7jUAxEv6FCpY+gm9gXMyABuph9Ex3BpQrD3HlDZ5E4ARbqFox+oUjWn18QnOGQSovNq73/8O+1Q7auHbJ17ZCta4dsXTtk69ohW9cO2br+c8izaZ0jFi6xtnYZIu6XFreY9fb4aCs7ykKO2niOR2uHmIa4HmfhjpOOuY/R3/Ri5cC6kKmtpyOQexcK2zS0E2HjhSC8bV11iDae73pDhvRXLjedoHTqlt8AUUrAHD3Oi/6KL6SOcG0oDhFfTseUhsEn8Nvyihj0OX/jSyGI4tMEWcD9fGFHVUjiRJAgOforuSKW8NvkKvJ51YPkm/tlUF7Mi3Dj0uDLetBLCcdErezKQkKOwPKoEiFpoGAKMi59hIvFg9pRGZJWgY2K00m7g92iil4cKCBOoqoQRPEqeXTCKESIJ1aBXHHEZJy+qmUlyDNFUdXhil/Qbm/EHvLo3fd3n1wH4pbgqTSxMvackDhZBeyDdURFtCjkCUsO5AWXwCWoYZjJmhEiTYOE4/E1yIUgQTMk0iw9u1eXDdUJmDOHEsZqKfoUhWAPyRXxhRJBhgQiwW4aZfFFrVJZiCKWddGBWckVREL1U81BzwZVjG9BrgMJ60PDFKYrWtwb2UK5VvacWhcyYZE7e8Qgdgobd1ed4v5wxThVhahLwiR1DINm+OIQafdZHkIuYaaKzK/TC0JQBfuFQzbFKhvwJcgkDPSgiH1TyzoQuwQljAsDrmhgUrY0NjIoHFxKqkJcJm/o4RWNhDmK2Msypod498m1ICOCcGEgNpErnpM2dmsLTVPODctCVBioi3ozYgtmjOLUeAxOSONUFsIdu6kTaOQlL0Gb0KOlpNNrbz0I8piCwGzIBbPZGtk3qkMYbKCrQuyUVBKj4Qgwhbohf1AKe2c/VoVQLMINEiwJ7KEbR6KIfXAlnYaqELMEjbQtUHI8eJwYDHhU5NoxvwW5FsRu0c1Bc9l44pQ8IbllFPEQRSF3+KGEgTQLSsGz1sHzsfZ6rApRsBr+iLo4YZdUIrAP1E9GJ9JNmFMVglWAL58SxgRpr3l5l9PCuhCU0W0gLsGe2BpJt+xZyQ+fBgpBuHN0TrRFZz1yYTwYzIrdJrwXi0IQMaIna3o3ymSIK2T+hlNK31gUQmGAL6qVKCN3K7rpiYFqJWx6HxGUgpgbGEWLBKShP+ztmdw3WzyrQmAJgRFpgolQUDBVHN0wNPjy7pRKQfj4iV3yFNAzgfVvz+gkWmkY6kKCNOm4jCG5aJSIOcDBF0PeI1YJ4v+I8I+0CYLQKQ4ZSrJGsYvKEAhiQ9T5IxAW+ZHmMRATr6oQm6Qn//ECeE2z3EZeTJ4N8ZXwY9WDEJPMkBsJgz5YMm0Vgqyhai5lIexJi0xeUDvy9VWPUCVMmqoQaoKVkXEAPllUQUH9m2I3pXGqClFKYIeZEhEsOmNrRtAzulfQMeJQUQi785NYVk1aQ5mGhdhRNhot89diUQnCV+BgTPIhDfiFPIFHaSlhKwxpsGSGL1o3aqWa4lQKt09eVSGJYxCCbip1JiRzdJfkHpnH7rWvHoRcMUEatFj9eeREFE/8Lxwn2CyXhXhE8NEbac8MfUaZRycRusljXQgxybaooQ9JkCFskQmWZwe1IWKEe4U1p8HMReic0IzFfXNxiGwBwyCPyvFH8OWSL3RWZUiQK2MaIi52zMZhGR/FIbDj5IvA3A0f/yARzMeCEcGUewtCNq0dsnXtkK1rh2xdO2Tr2iFb1w7ZunbI1vXLIX8AHeoU9l8JgBUAAAAASUVORK5CYII=",
    "mimeType": "image/png",
    "imageWidth": 400,
    "paymentLink": {
      "id": "9070cc13-1d41-4005-8dc8-bc0b8546d2bb",
      "expirationType": "DUE_DATE",
      "country": "BR",
      "url": "https://jpmorgan.net/pix/cobv/50c00b4e-2c1a-4a67-af21-d9ee18d74df6",
      "createdAt": "2024-10-01T20:23:46Z",
      "paymentRequestId": "e9d64e8be2f84f74b0bad614405881aa"
    },
    "text": "00020101021226880014br.gov.bcb.pix2566https://jpmorgan.net/pix/cobv/50c00b4e-2c1a-4a67-af21-d9ee18d74df65204000053039865802BR5927Sample JPM Client6008S. PAULO62360532e9d64e8be2f84f74b0bad614405881aa6304a4b2",
    "qrCodeType": "DYNAMIC"
  },
  "createdAt": "2024-10-01T20:23:47Z",
  "updatedAt": "2024-10-01T20:23:47Z",
  "expiresAt": "2024-12-02T00:00:00Z",
  "status": "ACTIVE"
}

Create a payment request by client ID

The request to pay API supports creating a payment request that uses a client provided transaction identifier. You can do this using the /payment-requests/{id} endpoint.

For more information see the Request to Pay via QR Code API specification.

Bulk Requests

The bulk request feature allows you to create multiple payment requests asynchronously using the /payments-requests/bulk endpoint. For more information see the Request to Pay via QR Code API specification.

Learn how to get the details of your payment request.