사용자 지정 결제 통합

이 문서는 Monetization이 기본으로 지원하지 않는 서드파티 결제 제공자에 대한 결제 처리 지원을 어떻게 제공하는지, 또는 Monetization 외부에서 통합 프로세스를 통해 결제 처리 로직을 직접 처리하기로 한 경우를 설명합니다.

Monetization의 서드파티 결제 처리

서드파티 결제 처리는 동기 방식과 비동기 방식의 두 가지 방법으로 수행할 수 있습니다. 동기 방식은 결제 통합 구성 요소에서 즉시 응답해야 하며, 비동기 방식은 Monetization에서 인보이스를 추출한 다음 나중에 결제를 가져오는 방식을 결합합니다.

정보:

일반적으로 사용 사례에 따라 어떤 처리 방식이 최적인지가 결정됩니다.

비동기 결제 처리

비동기 결제 처리에서는 Monetization에서 인보이스를 내보내고, 결제는 Monetization 외부에서 완전히 처리됩니다. 결제 처리 결과가 준비되면 CSV 파일 또는 Monetization API를 통해 가져옵니다.

인보이스 내보내기

invoice export mapper를 구성하고 SFTP 위치로 파일을 내보내는 exporting job을 예약하여 Monetization에서 인보이스를 내보낼 수 있습니다. 또는 Webhook을 통해 invoice creation을 구독하면 새 인보이스가 생성될 때마다 제공된 URL 주소로 invoice request가 트리거됩니다.

Exporting job - CSV 파일을 SFTP로

인보이스를 CSV 파일로 내보내려면 invoice parameter를 CSV 파일 열에 매핑하도록 Invoice Export mapper를 구성해야 합니다. Monetization User Interface에서는 Business configuration Export Invoice mappers 아래에서 이러한 구성을 수행할 수 있습니다.

Example of invoice export mapper configuration Figure 1: invoice export mapper 구성 예

Invoice export는 Exporting Jobs를 통해 예약되며, 일회성 작업이거나 특정 기간마다 자동으로 실행되도록 구성할 수 있습니다. Exporting Job은 내보낸 CSV 파일을 해당 SFTP 위치 storage/invoice/folder_name/file_name.csv에 저장합니다.

Example of invoice export job Figure 2: invoice export job 예

Notification - webhook 방식

webhook을 통해 인보이스를 내보내면 생성 즉시 인보이스를 받을 수 있습니다. 이는 Invoice Notification Rule을 구성하여 수행하며, 해당 rule은 생성된 모든 인보이스를 JSON body request로 제공된 URL 주소에 보내고 사전 구성된 header option도 함께 전달합니다.

Example of invoice creation webhook configuration Figure 3: invoice creation webhook 구성 예

결제 가져오기

payment import mapper를 구성하고 payment CSV 파일을 SFTP input location에 업로드하거나 Monetization REST API를 사용하여 결제 트랜잭션을 Monetization으로 가져올 수 있습니다.

SFTP를 통한 CSV 파일 가져오기

Monetization이 CSV 파일을 통해 결제 트랜잭션을 가져오려면 Payment Import Mapper가 구성되어 있어야 합니다. 구성은 Monetization User Interface의 Business configuration Import Payment mappers 아래에서 수행할 수 있습니다.

Payment mapper를 사용하면 CSV 열을 payment transaction parameter에 매핑하고 업로드된 파일에 존재해야 하는 파일 prefix를 정의할 수 있습니다.

파일은 SFTP server의 edl/input 폴더에 업로드되며, 처리 결과에 따라 edl/processed, edl/successful, edl/error, edl/rejected 폴더로 이동됩니다.

Example of payment import mapper configuration Figure 4: payment import mapper 구성 예

API 호출을 통한 가져오기

Monetization API를 통해 결제 트랜잭션을 가져오려면 트랜잭션 세부 정보가 포함된 JSON request를 Monetization REST API에 게시합니다.

참고:

사용자는 Monetization API와 통신하기 전에 먼저 인증되어야 합니다.

인증

Monetization API는 Bearer Token authentication을 사용합니다.

username, password, 특정 site code로 Authentication request를 실행합니다.
response에서 token을 가져옵니다.
이후 request에서 Authorization header를 Bearer <token>으로 설정합니다.
token은 5분 후 만료됩니다.

URL: {{api_url}}/authenticate

Headers
Content-Type:application/json

Body
{
    "username": "your_monetization_username",
    "password": "password",
    "site_code": "your_monetization_site_code - subdomain"
}

결제 가져오기 요청

URL: {{api_url}}/api/v1/import

Headers
Content-Type:application/json
Authorization:Bearer {{auth_token}}
Data-Type:Payment

Body
{
    "invoice_id": 123,
    "transaction_identifier": "T-1233-cew3-445f-feew3",
    "amount": 150,
    "transaction_time": 1600613169000,
    "currency": "EUR",
    "method": "other",
    "type": "charge",
    "provider": "stripe"
}

동기 결제 처리

동기 결제 처리는 Monetization과 결제 통합 구성 요소 간의 동기 통신이 필요합니다. 이 처리 방식은 신용/직불 카드 승인과 즉시 결제를 가능하게 합니다.

Monetization이 결제 처리 관련 request를 어디로 보낼지 지정하도록 구성하며, Monetization은 반환받을 것으로 예상하는 사전 정의된 response를 가지고 있습니다. 이 처리 방식은 고객에 payment method reference를 저장할 수 있게 하며 자동 결제 수금 프로세스를 지원합니다.

Monetization에서 통합 프로세스는 기존 제공자(Stripe, Braintree 등)와의 기본 통합과 사실상 동일합니다. 다만 통신은 사용자가 개발한 구성 요소를 통해 실행되며, 이 구성 요소는 로컬 결제 제공자로 가는 gateway 역할을 합니다.

Synchronous payment processing을 지원하는 필수 작업:

Setup Intent
Authorize
Capture
Charge

서드파티 결제 제공자 설정

서드파티 결제 제공자 통합을 설정하려면 third-party payment gateway profile을 구성하고 Monetization이 request를 보낼 URL을 제공합니다.

이는 UI의 System configuration Payment gateways 아래에서 수행하거나, Monetization REST API를 통해 Payment Gateway Profile을 생성하여 수행할 수 있습니다.

URL: {{api_url}}/api/v1/payment-gateway-profiles

Headers
Content-Type:application/json
Authorization:Bearer {{auth_token}}

Request
{
    "provider": "third-party",
    "headers": {
        "PGW_URL": "URL to your payment gateway"
    }
}

고객 작업

Customer operations는 서드파티 결제 제공자가 customer management를 지원하는 경우에만 적용됩니다. 결제 제공자가 customer management를 지원하지 않으면 customer ids를 어떤 값으로든 대체할 수 있습니다(예: request의 Unix timestamp).

customer 생성(카드 없음)

결제 제공자 서비스에 customer를 객체로 생성합니다.

Monetization이 보낸 request:

{
    "action": "create_customer",
    "content": {
        "customer": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        }
    }
}

예상 response:

HTTP Status: 201 Created

{
    "customer": {
        "id": "payment_provider_customer_id"
    }
}

customer 업데이트

결제 제공자 서비스의 customer 객체를 업데이트합니다.

Monetization이 보낸 request:

{
    "action": "update_customer",
    "content": {
        "customer": {
            "id": "payment_provider_customer_id_1",
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        }
    }
}

예상 response:

HTTP Status: 204 No Content

Response Body 없음

customer 조회

결제 제공자 서비스에서 customer 객체를 조회합니다.

{
    "action": "read_customer",
    "content": {
        "id": "payment_provider_customer_id_1"
    }
}

예상 response:

HTPP Status: 200 OK

{
    "content": {
        "customer": {
            "id": "payment_provider_customer_id_1",
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        },
        "credit_cards": [
            {
                "is_default": true,
                "card_holder_name": "John Anderson",
                "expiration_month": "03",
                "expiration_year": "2026",
                "type": "Mastercard",
                "token": "payment_provider_card_token",
                "last_four": "1234"
            }
        ]
    }
}

customer 삭제

결제 제공자 서비스에서 customer 객체를 삭제합니다.

Monetization이 보낸 request:

{
    "action": "delete_customer",
    "content": {
        "id": "payment_provider_customer_id_1"
    }
}

예상 response:

HTTP Status: 204 No Content

Response Body 없음

카드 작업

Card operations는 신용카드와 직불카드를 설정하거나 제거하는 작업을 의미합니다.

Setup(setup card request)

고객이 신용카드 세부 정보를 제공할 수 있는 프로세스를 트리거하며, 이 정보는 tokenized되어 Monetization에 저장됩니다. 새 신용카드를 추가하라는 request가 있으면 Monetization은 통합 구성 요소로 setup request를 보냅니다.

통합 구성 요소는 결제 제공자 서비스와 관련된 모든 로직을 처리하고 response로 redirect URL을 Monetization에 반환해야 합니다. 그러면 고객은 제공된 URL로 리디렉션되며, 결제 제공자가 호스팅하는 양식에서 고객의 카드 세부 정보를 수집하고 tokenized합니다.

Credit card setup Figure 5: 신용카드 setup

Monetization이 보낸 request:

{
    "action": "setup",
    "content": {
        "customer": {
            "id": "payment_provider_customer_id_1",
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        }
        "custom_attributes": {
            "callback_url": "https://callbackurl.com"
        }
    }
}

예상 response:

HTTP Status: 201 Created

{
    "customer": {
        "id": "payment_provider_customer_id"
    },
    "redirect_url": "https://card-data-collection-form.com"
}

card 삭제

payment provider services를 통해 credit card reference removal logic을 처리하도록 통합 구성 요소에 request를 보낸 다음, 성공 시 Monetization에서 reference를 제거합니다.

Monetization이 보낸 request:

{
    "action": "delete_credit_card",
    "content": {
        "customer": {
            "id": "provider_customer_id_34"
        },
        "credit_card": {
            "token": "provider_card_token_x23423532"
        }
    }
}

예상 response:

HTTP Status: 204 No Content

Response Body 없음

트랜잭션 작업

Transaction operations는 저장된 payment method(credit/debit card) token에 대해 실행되는 트랜잭션 동작을 의미합니다. 이러한 동작에는 다음이 포함됩니다.

Authorization
Capture
Charge
Void
Refund

Authorization

Authorization은 고객의 payment method에서 자금을 승인(잠금)하는 데 사용됩니다. Authorization은 나중에 Captured 또는 Voided될 수 있습니다. 아래 request는 통합 구성 요소로 전송되며, 통합 구성 요소는 payment provider service logic을 처리하고 response를 반환해야 합니다.

Monetization이 보낸 request:

{
    "action": "authorize",
    "content": {
        "amount": 20.5,
        "currency": "EUR",
        "customer": {
            "id": "provider_customer_id_34"
        },
        "credit_card": {
            "token": "provider_card_token_x23423532"
        }
    }
}

예상 response:

HTTP Status: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 25.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Capture

Capture는 이전 Authorization request에서 승인된 자금을 수금하는 것을 의미합니다. 수금할 금액은 승인된 금액과 같거나 더 낮을 수 있습니다.

수금되지 않은 승인 자금은 payment provider service에 의해 고객에게 다시 반환됩니다. 아래 request는 통합 구성 요소로 전송되며, 통합 구성 요소는 payment provider service logic을 처리하고 response를 반환해야 합니다.

Monetization이 보낸 request:

{
    "action": "capture",
    "content": {
        "transaction_id": "provider_transaction_id_t2134234",
        "amount": 10.5
    }
}

예상 response:

HTTP Status: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 10.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Charge

Charge는 자금 승인과 수금을 하나의 즉시 트랜잭션으로 수행합니다. 아래 request는 통합 구성 요소로 전송되며, 통합 구성 요소는 payment provider service logic을 처리하고 response를 반환해야 합니다.

Monetization이 보낸 request:

{
    "action": "charge",
    "content": {
        "amount": 25.5,
        "currency": "EUR",
        "customer": {
            "id": "provider_customer_id_34"
        },
        "credit_card": {
            "token": "provider_card_token_x23423532"
        }
    }
}

예상 response:

HTTP Status: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 25.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Void

Void operation은 Authorization transaction을 void하여 승인된 자금을 해제합니다. 아래 request는 통합 구성 요소로 전송되며, 통합 구성 요소는 payment provider service logic을 처리하고 response를 반환해야 합니다.

Monetization이 보낸 request:

{
    "action": "void",
    "content": {
        "transaction_id": "provider_transaction_id_t2134234"
    }
}

예상 response:

HTTP Status: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Refund

Refund는 고객에게 자금을 반환하며 이전 Charge 또는 Capture transaction을 참조합니다. 아래 request는 통합 구성 요소로 전송되며, 통합 구성 요소는 payment provider service logic을 처리하고 response를 반환해야 합니다.

Monetization이 보낸 request:

{
    "action": "refund",
    "content": {
        "transaction_id": "provider_transaction_id_t2134234",
        "amount": 10.5
    }
}

예상 response:

HTTP Status: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 25.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

오류 처리

통합 구성 요소에서 작업이 성공하지 못한 경우 200-300 범위를 벗어난 status와 error message를 response body에 반환합니다.

디바이스