# Paymongo for Node.js!

A lightweight Node.js client for Paymongo API.

![](/files/nAZxqJnbSEBaFIUfIweQ)

## Welcome to Paymongo for Node.js

A lightweight Node.js client for Paymongo API.

As seen on Paymongo's [community-made libraries](https://developers.paymongo.com/docs/community-made-libraries). :heart:

If you like this project, please give it a star, and consider following the author. :)

## Announcement

Maintaining open source projects regularly alone can lead to delay of updates and lower quality code. That's why moving forward, I decided to get more help by moving this project from my [personal GitHub account](https://github.com/jofftiquez) to [OSSPH's GitHub organization account](https://github.com/ossphilippines). This way I can get more help directly from OSSPH's amazing community, and hopefully, it will yield faster updates and more eyes watching the project. Thank you for your support! As always, please check the updated documentation below. If you're interested in OSSPH, please don't hesitate to learn more at <https://ossph.org>.

## Want to jump right in?

Feeling like an eager beaver? Jump into the quick start docs and get making your first request:

{% content-ref url="/pages/VnXGAel8vPdODBvouVTT" %}
[Quick Start](/quick-start)
{% endcontent-ref %}

## Want to deep dive?

Dive a little deeper and start exploring our API reference to get an idea of everything that's possible with the API:

{% content-ref url="/pages/qBiLN6jFAY84YF5i76S4" %}
[API Reference](/reference/api-reference)
{% endcontent-ref %}


# Quick Start

## Install

Install using either `yarn` or `npm`.

{% tabs %}
{% tab title="Yarn" %}

```
# Install via Yarn
yarn add paymongo
```

{% endtab %}

{% tab title="NPM" %}

```bash
# Install via NPM
npm install paymongo --save
```

{% endtab %}
{% endtabs %}

## Usage

Now, it's time to import the paymongo into your app.

```javascript
import Paymongo from 'paymongo';

const paymongo = new Paymongo(process.env.SECRET_KEY);
```

You must retrieve the secret key from your paymongo dashboard, under the developers tab.

## Example

```javascript
import Paymongo from 'paymongo';

const paymongo = new Paymongo(process.env.SECRET_KEY);

async function listWebhooks () {
  return paymongo.webhooks.list();
}

listWebhooks()
  .then((result) => { /** Handle result **/ })
  .catch();
```


# API Reference

You can also check Paymongo's [Official Documentation](https://developers.paymongo.com/docs).

## Payment Methods

A `PaymentMethod` resource describes which payment method was used to fulfill a payment. It is used with a PaymentIntent to collect payments.

{% content-ref url="/pages/4tMhxHBAD4ZEntEy0Yqh" %}
[Payment Methods](/reference/api-reference/payment-methods)
{% endcontent-ref %}

## Payment Intents

A `PaymentIntent` resource is used to track and handle different states of the payment until it succeeds.

{% content-ref url="/pages/r0Uzu7f4Gt3NCcNErdAU" %}
[Payment Intents](/reference/api-reference/payment-intents)
{% endcontent-ref %}

## Sources

A Source is a resource to generate your customer's payment instrument. This is normally used to generate check out URLs for e-wallet payments. To learn more about e-wallet integrations, you can visit [GCash](https://developers.paymongo.com/docs/accepting-gcash-payments) or [GrabPay](https://developers.paymongo.com/docs/accepting-grabpay-payments) integration.

{% content-ref url="/pages/cfmFkqRgSs8ILwg53sq0" %}
[Sources](/reference/api-reference/sources)
{% endcontent-ref %}

## Payments

A `Payment` resource is an attempt by your customer to send you money in exchange for your product. This is a reference to an amount that you are expecting to receive if a payment resource with paid status becomes a part of a payout. If the payment status is `failed`, you can determine the reason for failure.

{% content-ref url="/pages/Gvc60BnMN4YTvYNUK9od" %}
[Payments](/reference/api-reference/payments)
{% endcontent-ref %}

## Webhooks

A `Webhook` resource primarily refers to a certain URL where we send events that are happening from your account. You can check our [GCash](https://developers.paymongo.com/docs/accepting-gcash-payments) and [GrabPay](https://developers.paymongo.com/docs/accepting-grabpay-payments) integrations to find out some good use cases for webhooks.

{% content-ref url="/pages/KMqnQd9wE5KePcggOica" %}
[Webhooks](/reference/api-reference/webhooks)
{% endcontent-ref %}


# Links

A Link resource represents a one-time use link to receive a payment.

## The Link Resource

A `Link` resource represents a one-time use link to receive a payment.

[More Details](https://developers.paymongo.com/reference/links-resource#a-link-resource)

## Creating a Link

```javascript
/**
 * These are the required properties
 * @param {Object} data Data payload
 * @param {Object} data.attributes Payload attributes see full refence https://developers.paymongo.com/reference/links-resource#a-link-resource
 */
const result = await paymongo.links.create(data);

```

## Retrieving a Link

```javascript
/**
 * @param {string} id The Link id
 */
const result = await paymongo.links.retrieve(id);
```

## Get Link by Reference Number

```javascript
/**
 * @param {string} id The Link reference number
 */
const result = await paymongo.links.getByRef(reference_number);
```

## Archive a Link

```javascript
/**
 * @param {string} id The Link id
 */
const result = await paymongo.links.archive(id);
```

## Unarchive a Link

```javascript
/**
 * @param {string} id The Link id
 */
const result = await paymongo.links.unarchive(id);
```


# Payments

## The Payment Resource

A `Payment` resource is an attempt by your customer to send you money in exchange for your product. This is a reference to an amount that you are expecting to receive if a payment resource with paid status becomes a part of a payout. If the payment status is `failed`, you can determine the reason for failure.

[More Details](https://developers.paymongo.com/reference/payment-source)

## Creating a Payment

```javascript
/**
 * These are the required properties
 * @param {Object} data Data payload
 * @param {Object} data.attributes Payload attributes
 * @param {number} data.attributes.amount Amount int32
 * @param {number} data.attributes.currency Three-letter ISO currency code, in uppercase. PHP is the only supported currency as of the moment.
 * @param {Object} data.attributes.source The source object from checkout
 * @param {string} data.attributes.source.id Id of a Source resource
 * @param {string} data.attributes.source.type Type of a Source resource. Possible value is 'source'.
 */
const result = await paymongo.payments.create(data);

```

#### Payload

```javascript
{
  data: {
    attributes: {
      amount: 30000,
      currency: 'PHP',
      source: {
        id: 'abc', // Id of the Source resource.
        type: 'source', // 
      }
    }
  }
}

```

## Listing Payments

```javascript
const result = await paymongo.payments.list();
```

#### Results

```javascript
{
  data: [] // array of payments
}
```

## Retrieving a Payment

```javascript
/**
 * @param {string} id Payment id
 */
const result = await paymongo.payments.retrieve();

```


# Payment Intents

A \`PaymentIntent\` resource is used to track and handle different states of the payment until it succeeds.

## The Payment Intent Resource

A `PaymentIntent` resource is used to track and handle different states of the payment until it succeeds. To learn how to receive credit/debit card payments using PaymentIntent, you can check this [section](https://developers.paymongo.com/docs/accepting-cards). To learn how to receive PayMaya payments using PaymentIntent, you can check this [section](https://developers.paymongo.com/docs/accepting-paymaya-payments).

[More Details](https://developers.paymongo.com/reference/the-payment-intent-object)

## Creating a Payment Intent

```javascript
/**
 * These are the required properties
 * @param {Object} data The payload.
 * @param {Object} data.attributes Payload attributes.
 * @param {number} data.attributes.amount Amount to be collected by the PaymentIntent.
 * @param {string[]} data.attributes.payment_method_allowed The list of payment method types that the PaymentIntent is allowed to use. Possible value is card for now.
 * @param {string} data.attributes.currency Three-letter ISO currency code, in uppercase. PHP is the only supported currency as of the moment.
 */
const result = await paymongo.paymentIntents.create(data);

```

#### Payload

```javascript
{
  data: {
    attributes: {
      amount: 10000, // 10000 or 100 in money value is the smallest allowed amount.
      currency: 'PHP', // Three-letter ISO currency code. Only supports PHP for now.
      payment_method_allowed: ['card'] // The only available value for now is 'card'.
    }
  }
}

```

## Retrieving a Payment Intent

```javascript
/**
 * @param {string} id PaymentIntent id
 */
const result = await paymongo.paymentIntents.retrieve(id);

```

#### Attach to PaymentIntent

```javascript
/**
 * These are the required properties
 * @param {string} id PaymentIntent id.
 * @param {Object} data The payload.
 * @param {Object} data.attributes Payload attributes.
 * @param {string} data.attributes.payment_method Id of PaymentMethod to attach to the PaymentIntent.
 */
const result = await paymongo.paymentIntents.attach(id, data);

```

#### Payload

```javascript
{
  data: {
    attributes: {
      payment_method: 'abc123'
    }
  }
}

```

## Capture a PaymentIntent

```javascript
/**
 * @param {string} secret API private key
 * @param {string} id PaymentIntent id
 */
const result = await paymongo.paymentIntents.capture(id);
```

## Cancel a PaymentIntent

```javascript
/**
 * @param {string} secret API private key
 * @param {string} id PaymentIntent id
 */
const result = await paymongo.paymentIntents.cancel(id);
```


# Payment Methods

A \`PaymentMethod\` resource describes which payment method was used to fulfill a payment. It is used with a \`PaymentIntent\` to collect payments.

## The Payment Method Resource

A `PaymentMethod` resource describes which payment method was used to fulfill a payment. It is used with a `PaymentIntent` to collect payments.

[More Details](https://developers.paymongo.com/reference/the-payment-method-object)

## Creating a Payment Method

```javascript


/**
 * These are the required properties
 * @param {Object} data The payload.
 * @param {Object} data.attributes Payload attributes.
 * @param {string} data.attributes.type The type of payment method. The possible value is card for now.
 * @param {string} data.attributes.details.card_number Credit/Debit Card number of the PaymentMethod.
 * @param {number} data.attributes.details.exp_month Expiry month of the Credit/Debit Card.
 * @param {number} data.attributes.details.exp_year Expiry year of the Credit/Debit Card.
 * @param {string} data.attributes.details.cvc CVC of the Credit/Debit Card.
 */
const result = await paymongo.paymentMethods.create(data);

```

#### Payload

```javascript
{
  data: {
    attributes: {
      type: 'card', // The only available type for now is 'card'.
      details: {
        card_number: '4343434343434345',
        exp_month: 02,
        exp_year: 23,
        cvc: '123',
      }
    }
  }
}

```

## Retrieving a Payment Method

```javascript
/**
 * @param {string} id The PaymentMethod id
 */
const result = await paymongo.paymentMethods.retrieve(id);

```


# Refunds

Paymongo Refunds

## The Refund Resource

A Refund resource allows you to return full or partial amount of a payment to your customer's original payment method.

[More Details](https://developers.paymongo.com/reference/refund-resource)

## Creating a Refund

```javascript
/**
 * These are the required properties
 * @param {string} secret API private key
 * @param {Object} data Data payload
 * @param {Object} data.attributes Payload attributes
 * @param {number} data.attributes.amount Amount of the refund. A positive integer with minimum amount of 100. See https://developers.paymongo.com/reference/create-a-refund
 * @param {string} data.attributes.notes Notes of the refund. You can use this value to save remarks about the refund. The maximum characters is 255.
 * @param {string} data.attributes.payment_id The ID of a Payment resource to be refunded.
 * @param {string} data.attributes.reason Reason for the refund. Possible values are duplicate, fraudulent, requested_by_customer and others.
 * @param {Object} data.attributes.metadata A set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the object in a structured format. Only string values are accepted.
 */asc
const result = await paymongo.refunds.create(data);
```

#### **Payload**

```json
{
  "data": {
    "id": "ref_vPSqdAPD2pmtKj6Ac5SRfXjs",
    "type": "refund",
    "attributes": {
      "amount": 10000,
      "currency": "PHP",
      "livemode": true,
      "notes": "Double payment created",
      "payment_id": "pay_qOShdAuD3p8tKa6Ac4SRfbjs",
      "payout_id": null,
      "reason": "requested_by_customer",
      "status": "succeeded",
      "created_at": 1612746914,
      "updated_at": 1612746914
    }
  }
}
```

## **Listing Refunds**

```javascript
const result = await paymongo.refunds.list();
```

## Retrieving a Refund

```javascript
/**
 * @param {string} id ID of a Refund
 */
const result = await paymongo.refunds.retrieve(id);
```


# Sources

A Source is a resource to generate your customer's payment instrument.

## The Source Resource

A Source is a resource to generate your customer's payment instrument. This is normally used to generate check out URLs for e-wallet payments. To learn more about e-wallet integrations, you can visit [GCash](https://developers.paymongo.com/docs/accepting-gcash-payments) or [GrabPay](https://developers.paymongo.com/docs/accepting-grabpay-payments) integration.

[More Details](https://developers.paymongo.com/reference/the-sources-object)

## Creating a Source

```javascript
/**
 * These are the required properties
 * @param {Object} data Data paypload
 * @param {Object} data.attributes Payload attributes
 * @param {string} data.attributes.type The type of source. Possible values are gcash and grab_pay.
 * @param {number} data.attributes.amount Amount int32
 * @param {string} data.attributes.currency Three-letter ISO currency code, in uppercase. PHP is the only supported currency as of the moment.
 * @param {Object} data.attributes.redirect
 * @param {string} data.attributes.redirect.success Success url
 * @param {string} data.attributes.redirect.failed Error url
 */
const result = await paymongo.sources.create(data);

```

```javascript
{
  data: {
    attributes: {
      type: 'gcash',
      amount: 20000, // PHP200,
      currency: 'PHP',
      redirect: {
        success: 'https://yoururl.com/success',
        failed: 'https://yoururl.com/failed'
      }
    }
  }
}

```

## Retrieving a Source

```javascript
/**
 * @param {string} id Source id
 */
const result = await paymongo.sources.retrieve(id);

```


# Webhooks

Webhooks

## The Webhook Resource

A `Webhook` resource primarily refers to a certain URL where we send events that are happening from your account. You can check the [webhook](https://developers.paymongo.com/docs/webhooks) section of our integration guide to find out some good use cases for webhooks.

[More Details](https://developers.paymongo.com/reference/webhook-resource)

## Creating a Webhook

```javascript
/**
 * These are the required properties
 * @param {Object} data Data payload
 * @param {Object} data.attributes Payload attributes
 * @param {string} data.attributes.url The destination URL of the events that happened from your account. Please make sure that the URL is publicly accessible in order for you to receive the event.
 * @param {string[]} data.attributes.events The list of events to be sent to this webhook. Possible value in the meantime is source.chargeable.
 */
const result = await paymongo.webhooks.create(data);

```

#### Payload

```javascript
{
  data: {
    attributes: {
      url: 'https://yourwebsite.com/webook-listener', // Developer's note: this is unique in paymongo. You can't create multiple webhooks with same url.
      events: ['source.chargeable'] // The only event supported for now is 'source.chargeable'.
    }
  }
}

```

## Listing Webhooks

```javascript
const result = await paymongo.webhooks.list();
```

#### Resultjavas

```javascript
{
  data: [] // Array of webhooks
}
```

## Retrieving a Webhook

```javascript
/**
 * @param {string} id Webhook id
 */
const result = await paymongo.webhooks.retrieve(id);

```

## Toggling a Webhook

Enable or disable a webhook.

```javascript
/**
 * @param {string} id Webhook id
 * @param {string} action Toggle options 'enable' or 'disable'
 */
const result = await paymongo.webhooks.toggle(id, action);

```


# Test Cards

You can use these test cards to test your implementation.

<table><thead><tr><th width="232">Card Number</th><th width="200">Brand</th><th width="150">CVC</th><th>Expiration Date</th></tr></thead><tbody><tr><td>4343434343434345</td><td>Visa</td><td>Any 3 digits</td><td>Any future date</td></tr><tr><td>4571736000000075</td><td>Visa (debit)</td><td>Any 3 digits</td><td>Any future date</td></tr><tr><td>5555444444444457</td><td>Mastercard</td><td>Any 3 digits</td><td>Any future date</td></tr><tr><td>2221000000000918</td><td>Mastercard (2-series)</td><td>Any 3 digits</td><td>Any future date</td></tr><tr><td>5455590000000009</td><td>Mastercard (debit)</td><td>Any 3 digits</td><td>Any future date</td></tr><tr><td>5339080000000003</td><td>Mastercard (prepaid)</td><td>Any 3 digits</td><td>Any future dat</td></tr></tbody></table>

More cards [here](https://developers.paymongo.com/docs/testing), including [3D Secure Test Cards](https://developers.paymongo.com/docs/testing#section-3-d-secure-test-card-numbers).


# Change Logs

## 2023-05-12

{% embed url="<https://github.com/OSSPhilippines/paymongo/releases/tag/v1.3.2>" %}
Release v1.3.2
{% endembed %}

{% embed url="<https://github.com/OSSPhilippines/paymongo/releases/tag/v1.3.0>" %}
Release v1.3.0
{% endembed %}

## 2022-12-6

* Add [`links`](/reference/api-reference/links) API
* Add `capture` and `cancel` methods to [PaymentIntents](/reference/api-reference/payments)
* Move repo to <https://github.com/ossphilippines>

## Old

* Add `retrieve` function to sources.
* New syntax patterned with Stripe's Node.js library.
* Enhance method verbs
* Deprecate **Tokens**. See deprecation note [here](https://developers.paymongo.com/reference#token-resource).


# FAQs

* How to make payment using Gcash or GrabPay?
  * GCash guide - <https://developers.paymongo.com/docs/accepting-gcash-payments>
  * GrabPay guide - <https://developers.paymongo.com/docs/accepting-grabpay-payments>
* How to test a webhook?
  * I have a web application still in development for testing any webhooks. Follow this repo for updates.