# APM Integration Guide

## Enabling Alternative Payment Methods (APMs)

To activate an alternative payment method on MoneyCollect, merchants can easily apply through their dashboard. This process involves toggling a switch to submit an application for the desired payment method, awaiting approval. Additional information might be required for some local payment methods, such as a local service phone number.

For detailed instructions, visit: [Apply for APMs from your dashboard - MoneyCollect Documentation](https://docs.moneycollect.com/documentation/business-operation/alternative-payment-methods/apply-for-apms-from-your-dashboard).

## Utilizing Payment Methods

Once your application for a payment method is approved, you can start integrating it into your payment processes.

### Hosted Payment Page

To initiate a payment session via the API, you can follow the guide and API reference provided by MoneyCollect: [Create a Session | MoneyCollect API Reference V1.0](https://apireference.moneycollect.com/docs/api-v1/ac48ebdba6798-create-a-session).

Example request to create a session:

```java
POST https://api.moneycollect.com/api/services/v1/checkout/session/create
```

```json
{
  "paymentMethodTypes": ["card", "pix", "ame", "paypal"]
}
```

The `paymentMethodTypes` parameter allows specifying multiple payment methods. You can find the necessary payment method codes in the MoneyCollect documentation: [Supported APM codes and attributes list](https://docs.moneycollect.com/documentation/payment-integration/payment-methods/support).

<figure><img src="https://3906929740-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQyT5pndc80PGeNrMulEU%2Fuploads%2FiIvdRRIFjYvnOsCoWAi6%2F1.png?alt=media&#x26;token=c4554209-16e7-451d-af46-a8fed2aef745" alt=""><figcaption></figcaption></figure>

Example response:

```java
{
  "code": "success",
  "msg": "success",
  "data": {
    "id": "cs_17522182534xxxxx",
    "amountTotal": "990",
    "currency": "USD",
    "paymentMethodTypes": ["card", "pix", "ame", "paypal"],
    "cancelUrl": "http://localhost:4242/cancle.html",
    "returnUrl": "http://localhost:4242/return.html",
    "notifyUrl": "http://localhost:4242/notify.html",
    "orderNo": "order_id_123456",
    "website": "http://yourwebsite.org",
    "paymentId": "pt_17522182529xxxxxx",
    "url": "https://payment.moneycollect.com/checkout/cs_175221825xxxxxxxx#bGl2ZV9UhQUxxxxxxxxxx",
    "status": "unpaid",
    "created": "2022-01-30T06:32:40.932Z"
  }
}
```

After successfully creating a session, verify the amount, currency, and transaction status. Use the returned URL for the next step of the payment process, where customers choose a payment method and are redirected to the payment page.

<figure><img src="https://3906929740-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQyT5pndc80PGeNrMulEU%2Fuploads%2FmIQJ0h9jBqbUSPlmEtDm%2F2.png?alt=media&#x26;token=c6872770-be7e-4ab8-83fc-79b1b102e5e4" alt=""><figcaption></figcaption></figure>

### In-Page Payment

For In-Page Payment integration, specify multiple payment methods during the payment creation process in a similar manner as shown above.

Example parameter:

```json
"paymentMethodTypes": [
     "card",
     "pix",
     "ame",
     "paypal" 
  ]
```

### API-Direct

The API-Direct integration mode enables our PCI-compliant partner to facilitate local payment methods in server-to-server payment processing.

#### **1. Create PaymentMethod**

[Create a paymentMethod](https://apireference.moneycollect.com/docs/api-v1/4ae9a5a4bddc4-create-a-payment-method) first and obtain the Payment Method ID for the next step.

Example request:

```java
POST  https://api.moneycollect.com/api/services/v1/payment_methods/create
```

```json
{
  "billingDetails": {
    "address": {
      "city": "Asheville",
      "country": "US",
      "line1": "3968 Fidler Drive",
      "line2": "",
      "postalCode": "28806",
      "state": "North Carolina"
    },
    "email": "funny@moneycollect.com",
    "firstName": "Mark",
    "lastName": "Merrill",
    "phone": "6533714563"
  },
  "card": {
    "cardNo": "",
    "expMonth": "",
    "expYear": "",
    "securityCode": ""
  },
  "pix": {
    "taxId": "11032341882"
  },
  "boleto": {
    "taxId": "11032341882"
  },
  "type": "pix"   
}
```

Use the `type` parameter to specify the payment method code you wish to use. The payment method code list can be retrieved from the [Supported APM codes and attributes list](https://docs.moneycollect.com/documentation/payment-integration/payment-methods/support) on MoneyCollect's documentation. Please make sure that the payment method has been applied and approved in your dashboard before using it in the production environment.

Example response:

```java
{
	"code": "success",
	"msg": "success",
	"data": {
		"id": "pm_17543443642xxxxx",
		"type": "pix",
		"billingDetails": {
			"firstName": "Mark",
			"lastName": "Merrill",
			"phone": "6533714563",
			"email": "funny@moneycollect.com",
			"address": {
				"city": "Asheville",
				"country": "US",
				"line1": "3968 Fidler Drive",
				"line2": "",
				"postalCode": "28806",
				"state": "North Carolina"
			}
		},
		"created": "2022-02-04T07:20:49.363Z",
		"customerId": null,
		"card": null,
		"boleto": null,
		"pix": null
	}
}
```

#### **2. Create a Payment**

Use the Payment Method ID obtained in the previous Create PaymentMethod step to initiate the [Create a Payment](https://apireference.moneycollect.com/docs/api-v1/459a230b2245a-create-a-payment) request.

Example request:

```java
POST https://api.moneycollect.com/api/services/v1/payment/create
```

```java
{
  "amount": 990,
  "currency": "USD",
  "orderNo": "SGUJDAU0-0005",
  "notifyUrl": "https://notifyUrl",
  "returnUrl": "https://returnUrl",
  "ip": "14.153.236.144",
  "paymentMethod": "pm_17543443642xxxxx",
  "paymentMethodTypes": [
    "pix"
  ],
  "confirm": true,
  "website": "https://fanyi.baidu.com"
}
```

Example response:

```json
{
	"code": "success",
	"msg": "success",
	"data": {
		"id": "pt_1754346087365287938",
		"amount": "990",
		"currency": "USD",
		"paymentMethod": "pm_1754346064963510273",
		"paymentMethodTypes": [
			"pix"
		],
		"paymentMethodType": "pix",
		"notifyUrl": "https://notifyUrl",
		"returnUrl": "https://returnUrl",
		"website": "https://fanyi.baidu.com",
		"ip": "14.153.236.144",
		"clientSecret": "pt_1754346087365287938_secret_42A78177CEEBB8A60CE629FD4A99648B",
		"created": "2022-02-05T03:27:56.062Z",
		"nextAction": {
			"type": "redirect",
			"redirectToUrl": "https://checkout.xxx.com/checkout?prepay_id=QVViS0N5Znh1dzVXZzxxxxxx"
		},
		"status": "requires_action",
		"displayStatus": "pending",
		"errorCode": null,
		"errorMessage": null,
		"invoiceId": null,
		"fromChannel": null,
		"use3D": false
	}
}
```

#### 3.Redirecting to Payment Page

After creating a payment, use the `redirectToUrl` from the response to redirect customers to the payment page of the local payment institution to complete the transaction.

<figure><img src="https://3906929740-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQyT5pndc80PGeNrMulEU%2Fuploads%2FViP8HVctWzvSTX7kQd6W%2F2.png?alt=media&#x26;token=d899eaef-807c-423b-969a-ab62cae42831" alt=""><figcaption></figcaption></figure>

#### 4. Completing the Payment

Customers will be redirected to the local payment institution's page, where they can scan a QR code or enter the necessary payment information to finalize the payment.

## Special Handling APMs (Wechat Pay/Kakao Pay)

### Wechat Pay

{% file src="https://3906929740-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQyT5pndc80PGeNrMulEU%2Fuploads%2Fk2IYMNPHddl9j9gpjNOt%2F%E5%BE%AE%E4%BF%A1%E6%94%AF%E4%BB%98%E5%AF%B9%E6%8E%A5%E6%96%87%E6%A1%A3.pdf?alt=media&token=5cc659e7-8943-429d-b9b9-23a263f5b60f" %}
